Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

8313424: JavaFX controls in the title bar #1605

Open
wants to merge 28 commits into
base: master
Choose a base branch
from

Conversation

mstr2
Copy link
Collaborator

@mstr2 mstr2 commented Oct 20, 2024

Implementation of EXTENDED stage style.


Progress

  • Change must not contain extraneous whitespace
  • Change requires a CSR request matching fixVersion jfx24 to be approved (needs to be created)
  • Commit message must refer to an issue
  • Change must be properly reviewed (2 reviews required, with at least 2 Reviewers)

Issue

  • JDK-8313424: JavaFX controls in the title bar (Enhancement - P4)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jfx.git pull/1605/head:pull/1605
$ git checkout pull/1605

Update a local copy of the PR:
$ git checkout pull/1605
$ git pull https://git.openjdk.org/jfx.git pull/1605/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 1605

View PR using the GUI difftool:
$ git pr show -t 1605

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jfx/pull/1605.diff

Using Webrev

Link to Webrev Comment

@bridgekeeper
Copy link

bridgekeeper bot commented Oct 20, 2024

👋 Welcome back mstrauss! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

@openjdk
Copy link

openjdk bot commented Oct 20, 2024

❗ This change is not yet ready to be integrated.
See the Progress checklist in the description for automated requirements.

@openjdk openjdk bot added the rfr Ready for review label Oct 20, 2024
@mlbridge
Copy link

mlbridge bot commented Oct 20, 2024

@mstr2
Copy link
Collaborator Author

mstr2 commented Oct 20, 2024

/reviewers 2 reviewers
/csr

@openjdk
Copy link

openjdk bot commented Oct 20, 2024

@mstr2
The total number of required reviews for this PR (including the jcheck configuration and the last /reviewers command) is now set to 2 (with at least 2 Reviewers).

@openjdk openjdk bot added the csr Need approved CSR to integrate pull request label Oct 20, 2024
@openjdk
Copy link

openjdk bot commented Oct 20, 2024

@mstr2 has indicated that a compatibility and specification (CSR) request is needed for this pull request.

@mstr2 please create a CSR request for issue JDK-8313424 with the correct fix version. This pull request cannot be integrated until the CSR request is approved.

@Glavo
Copy link
Contributor

Glavo commented Oct 20, 2024

Hey, I'm glad to see this PR, but do you have any ideas for continuing to provide UNDECORATED_INTERACTIVE in the future? I think UNDECORATED_INTERACTIVE is more useful than EXTENDED for users who want to provide a consistent UI on different platforms.

@tsayao
Copy link
Collaborator

tsayao commented Oct 20, 2024

Very nice. I'll test on Linux and report back.

@mstr2
Copy link
Collaborator Author

mstr2 commented Oct 20, 2024

Hey, I'm glad to see this PR, but do you have any ideas for continuing to provide UNDECORATED_INTERACTIVE in the future? I think UNDECORATED_INTERACTIVE is more useful than EXTENDED for users who want to provide a consistent UI on different platforms.

The only difference between the two would be whether the default window buttons are provided. I don't see how a window without default window buttons would be more useful. Even heavily stylized apps like Spotify use window buttons that feel at home on the OS, that doesn't take away from a consistent look and feel.

@tsayao
Copy link
Collaborator

tsayao commented Oct 21, 2024

A few points observed on Linux:

  1. It's possible to resize it to 1px using the provided functionality with gtk_window_begin_resize_drag. An then it's not possible to resize back. The Headerbar should block resizing to the size of window controls.
  2. It's not possible to move the window if the cursor is over a control. Maybe you should just gtk_window_begin_move_drag when a drag is detected, not on click. That would be on WindowContextBase::process_mouse_motion;
  3. The application is closing if the click happens on the top right corner (that's because it's triggering the close button instead of resizing (I think 2 should solve it as well). It closes with:
    (java:16179): Gtk-CRITICAL **: 07:34:26.721: gtk_window_begin_resize_drag: assertion 'gtk_widget_get_visible (widget)' failed
  4. Alt + F8 is working (it's a desktop shortcut for resizing the window) - just pointing out to include in manual testing;
  5. I think rounded edges should be supported on the HeaderBar, since it's the default on gnome. For that to work, EXTENDED should be also transparent on Linux. It would loose the window drop shadow which can be added on the JavaFX side. gdk_window_set_shadow_width should be called with the drop shadow size, so the desktop will know the correct window bounds.

Added later:
6) It should have a "focused" state/pseudo class because on gnome (maybe others) the focused window has a different background on the HeaderBar which is darker.
7) Suggestion: Maybe make window states stylable on the HeaderBar with pseudo-classes like :maximized, :fullscreen, :focused, :solid (when it does not have rounded corners). Then it would be possible to CSS style it.
8) Maybe integrate with platform preferences and provide a way to CSS style it when it's Light or Dark?

Nice cleanup on Window.java . UndecoratedMoveResizeHelper was not going to work on Linux anyways.

@andy-goryachev-oracle
Copy link
Contributor

I suggest we convert this PR to Draft and first discuss this in the mailing list.

There are so many issues with the proposal that need to be ironed first: CSS support, height limitation (what happens when the app or CSS places too large of the component?), user-defined color/accents/transparency on Windows, to name just a few.

This change also may add a significant maintenance burden to the platform, for what I feel is a very small payout.

What do you think?

@mstr2
Copy link
Collaborator Author

mstr2 commented Oct 21, 2024

I suggest we convert this PR to Draft and first discuss this in the mailing list.

This has already been discussed at various points in time, and was always received positively. The previous implementation is one of the most-upvoted feature proposals since OpenJFX moved to GitHub.

There are so many issues with the proposal that need to be ironed first: CSS support, height limitation (what happens when the app or CSS places too large of the component?), user-defined color/accents/transparency on Windows, to name just a few.

What about these things? I don't understand the question, but let me try to give some answers nontheless:

  1. CSS support: HeaderBar is a normal part of the scene graph, so it fully supports CSS styling.
  2. Height limitation: the height of HeaderBar is user-configurable, just like any layout container. It can be as large as you want.
  3. User-defined color/accents/transparency: Again, since HeaderBar is a part of the scene graph, all rules are the same.

This change also may add a significant maintenance burden to the platform, for what I feel is a very small payout.

Popular demand says otherwise.

@andy-goryachev-oracle
Copy link
Contributor

Popular demand is good, but I would like to hear from the tech leads and the maintainers.

@andy-goryachev-oracle
Copy link
Contributor

To clarify about height: do all the platforms support arbitrary height? What if size set by the app/CSS exceeds the height supported by the platform?

About platform preferences: will it support all the attributes of the window decorations provided by the platform?

@mstr2
Copy link
Collaborator Author

mstr2 commented Oct 21, 2024

To clarify about height: do all the platforms support arbitrary height? What if size set by the app/CSS exceeds the height supported by the platform?

Yes, all platforms support header bars of arbitrary height. You can make the header bar the size of the entire window, in which case everything is draggable.

About platform preferences: will it support all the attributes of the window decorations provided by the platform?

If by "attributes" you mean the default behavior of platform decorations, then the anwer is mostly. These are the behaviors that are available on every platform:

  1. A resize border.
  2. Minimize, maximize, and close buttons (this includes all states these buttons can be in: available/deactivated/disabled).
  3. Click-and-drag on the header bar.
  4. Double-click to maximize on the header bar.

On Windows, native window decorations also have the "system menu", which is this thing that appears when you click on the program icon:
Ml7Pf

EXTENDED windows have no system menu, because they have no program icon.
Edit: they now have a system menu that opens with a right click on the header bar.

@mstr2
Copy link
Collaborator Author

mstr2 commented Oct 21, 2024

@tsayao Thanks for the comments. I'll have a look at the bugs that you found.

  1. It's not possible to move the window if the cursor is over a control. Maybe you should just gtk_window_begin_move_drag when a drag is detected, not on click. That would be on WindowContextBase::process_mouse_motion;

I know that dragging on interactive controls is a thing on Linux, but I don't think that we should be doing that. JavaFX applications are multi-platform apps, which means that their behavior should be consistent across platforms. Stealing mouse interactions on interactive controls is not a thing on Windows and macOS, and this has the potential to cause problems for application developers.

If you want, you can declare any node in the header bar to be draggable on all platforms with HeaderBar.setDraggable(Node, boolean).

  1. I think rounded edges should be supported on the HeaderBar, since it's the default on gnome. For that to work, EXTENDED should be also transparent on Linux. It would loose the window drop shadow which can be added on the JavaFX side. gdk_window_set_shadow_width should be called with the drop shadow size, so the desktop will know the correct window bounds.

I'll have to look into that, but in general an EXTENDED window should work out of the box for all platforms, without platform-specific changes on the JavaFX side.

Added later: 6) It should have a "focused" state/pseudo class because on gnome (maybe others) the focused window has a different background on the HeaderBar which is darker. 7) Suggestion: Maybe make window states stylable on the HeaderBar with pseudo-classes like :maximized, :fullscreen, :focused, :solid (when it does not have rounded corners). Then it would be possible to CSS style it. 8) Maybe integrate with platform preferences and provide a way to CSS style it when it's Light or Dark?

While that sounds useful at first, I don't think it carries its own weight. Many platforms use different styling for windows that are focused vs. windows that are not. This not only includes the header bar, but many other parts of the user interface as well. I don't think that we should be adding what would essentially be ad-hoc pseudo-classes only to HeaderBar.

In addition to that, it is extremely easy for an application to do this by adding a listener to Stage.focused and then toggling pseudo-classes on all relevant controls.

We should definitely not do pseudo-classes for light vs. dark mode. The correct way to solve this problem is with media queries (prefers-color-scheme).

@mlbridge
Copy link

mlbridge bot commented Oct 22, 2024

Mailing list message from quizynox at gmail.com on openjfx-dev:

Hello,

Thank you so much for your effort! I'm really glad this hasn't been
forgotten. I wouldn't say it's just popular demand; it's an absolute must.
Here are a few thoughts, if you don't mind.

Every modern platform supports this feature: Electron, Tauri, Wails, Qt,
and even Swing via FlatLaf. If you use IntelliJ or VSCode, you can see it
for yourself. It's a popular design trend, which is why there's so much
demand.

Unfortunately, the current UNDECORATED stage implementation lacks two
important things: shadows and smooth resizing. Implementing shadows is
tricky but possible. However, achieving smooth resizing with Java code
alone is not feasible. There are several implementations on StackOverflow,
but they tend to be jerky and not very performant.

That's why the implementation should be handled on the native side, which
isn't something an app developer can do. We can only patiently wait for
this feature to be integrated into the core JavaFX platform.

It's indeed a complex feature. For that reason, I believe the
implementation shouldn't provide platform-dependent window controls. It
should be left to app developers to dodge theming issues. In Linux, for
example, it's common to install 3rd-party themes or decorations. You never
know what decorations the end user will use, and OS developers can change
themes over time too. It's just simpler to support this feature as a
separate library, which I'm sure will be developed.

??, 22 ???. 2024??. ? 03:24, Michael Strau? <mstrauss at openjdk.org>:

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/openjfx-dev/attachments/20241022/367f812e/attachment-0001.htm>

@tsayao
Copy link
Collaborator

tsayao commented Oct 22, 2024

I think we should look at use cases and design a simple solution that can be extended.

Doing this with JavaFX as it is now will be hacky, since it would need to touch internals that are not exposed by default.

Intellij Idea
image

Nautilus
image

Chrome
image

Amberol (music player).
image

App Center (Ubuntu Software Store) - This one uses flutter
image

Some of them has no title at all. Some fuses the HeaderBar with the body, like nautilus. Even chrome, the tabs on the HeaderBar are not "isolated" from the body.

On modern Gnome, everything is client side decorated. Server side decoration is legacy. It's better for rendering since the window manager does not need to calculate, draw and sync with the window. It's probably less flickery.

Since JavaFx accounts the title as part of the window size, the current glass implementation is very hacky because it needs to request the decoration sizes from the window manager and then recalculate it. Having it on the client side is better, because no hacky solution is required.

@nlisker
Copy link
Collaborator

nlisker commented Oct 22, 2024

Adding some more examples.

Vivaldi browser actually allows you to switch between two modes:
image

which can be switched with
image

to
image

So in the first mode, the menu is compressed vertically into the Vivaldi button.

Here is Discord:
image

Very compact.

As for the payout of this feature, while personally I don't have a need for it, I will probably use it if it's not too much trouble. Regardless of my own opinion, this has been one of the most requested features, along with tray icon support, and it's available in the main "competition" frameworks. I would say that a very strong case will need to be made for this to not be added. The question that remains, as it often does, is if this is the right implementation. Hopefully the review process will figure that out.

@mstr2
Copy link
Collaborator Author

mstr2 commented Oct 22, 2024

I would advise all commenters to look at the proposal which is presented, understand the trade-offs being made, and only then criticize the design decisions and offer suggestions.

This feature is designed in a particular way because it needs to work on all supported platforms (not just the one you happen to like most). Here are the main design decisions that I made along the way:

Multi-platform

Since JavaFX is a multi-plattform framework, this feature must work out of the box on all supported platforms. It is a non-starter to require application developers to add platform-specific code to their applications if they want to use this feature.

This rules out things like requiring developers to add JavaFX shadows to their application because Linux doesn't provide the shadows for us. If we require JavaFX shadows, we must do that without intervention of application developers. We also shouldn't add platform-specific configuration switches.

Ease of use

It must be easy to use. In particular, this means that default window interactions must work reliably and feel at home on the OS. If possible, we will use platform-native window buttons instead of crafting our own bespoke versions (the macOS implementation does just that).

If you look at many examples of applications that extend the client area into the title bar, you will notice that most good examples don't re-invent window buttons in their totality, but either use platform-native buttons or at least use lookalike-versions of the platform buttons.

Window buttons require quite a bit of effort to get it just right. It's way more effort than just throwing a bunch of buttons in the window corner and calling it a day. Window buttons need to interact with the OS in very specific ways to enable features like snap layouts (on Windows). And what about right-to-left locales? Again, please understand the design constraints before offering alternatives.

Customizability

It is an explicit non-goal of this PR to offer a way to customize the window buttons. That's because at least on macOS, there is simply no way to do that with the OS-native buttons. If we allowed for customization only for Windows and Linux, but not for macOS, we would again run into the problem of falling short of our multi-platform compatibility goal.

In addition to that, most application developers will not want to customize the window buttons. Just look at the examples of applications that have already been posted, and you'll notice that window buttons are not gratuitously different, they at least try to feel at home on the target OS.

Shifting all of the implementation burden for window buttons to application developers is the wrong framing for this feature. We're not trying to build a feature that mainly caters to the few applications with crazy custom user interfaces, we're trying to build a feature for the 99%.

@andy-goryachev-oracle
Copy link
Contributor

andy-goryachev-oracle commented Oct 22, 2024

Continuing on window attributes. I would like to know what is and is not supported by platform, by feature.

For example:

Windows

  • translucency
  • color gradient
  • system menu on right click, on the toolbar and on the app components
  • color accent on hover over window buttons
  • window borders
  • round corners
  • double click to maximize
  • drag to reposition the window
  • dark/light theme
  • accessibility: keyboard focus, accessible focus, narrator

Did I miss anything?

@andy-goryachev-oracle
Copy link
Contributor

For the HeaderBar, I would like to see the explanation of different layout options, including the cases when all the information does not fit the window width. Which parts are contracted? How is overflow handled?

@andy-goryachev-oracle
Copy link
Contributor

andy-goryachev-oracle commented Oct 22, 2024

May be I am late to the party, but I would suggest to discuss the JEP first. I would like to see the summary by platform by feature, I would like to see details of the layout, and the description if and how the proposed design responds to user preferences changes dynamically.

I would also like to see alternatives. Perhaps the app developers has all the tools already (for example, creating an overlay transparent scene on top of the platform title bar?), or maybe this functionality should be rather implemented in a library.

Lastly, there is a concern of adding a huge maintenance burden on the platform. Next time the major OS vendor changes the L&F or adds something to the window decorations, we are on the hook for supporting that.

I am not even qualified to access the impact of this feature in the Linux world. There are so many frameworks and opinions - how do you propose to handle that? Is it going to be supported on Wayland?

@tsayao
Copy link
Collaborator

tsayao commented Oct 22, 2024

Gtk does work on Mac and Windows, maybe we can see how it handles it's HeaderBar, for reference.

@andy-goryachev-oracle
Copy link
Contributor

Another aspect is whether this should be a conditional feature.
If not, how will it be supported on Android/iOS? RaspPI?

@mstr2
Copy link
Collaborator Author

mstr2 commented Oct 28, 2024

the exception is gone, the flicker remains.

Can you verify? I can't observe it on my system with the latest fix.

@andy-goryachev-oracle
Copy link
Contributor

no flicker on win11, thanks!

the height of the title bar is slightly off. I think it should be the same as the native title bar of DECORATED window.

@mstr2
Copy link
Collaborator Author

mstr2 commented Oct 29, 2024

I think it should be consistent: it is, after all, the minimum height.

Applications that want larger title bar can easily achieve that, but the minimum height must be set to the same height as the standard javaFX-created window.

I've made the window buttons adapt dynamically to the header bar height on macOS. Without a user-provided minHeight, the header bar starts out in the smallest possible configuration (that's the classic layout). Then, as the actual height increases, the window buttons are laid out for medium and large layouts. The cutoff heights for small, medium, and large layouts are 28px, 38px, and 52px respectively.

@andy-goryachev-oracle
Copy link
Contributor

andy-goryachev-oracle commented Oct 30, 2024

it looks like the default hight of the HeaderBar is consistent with the native title bar on mac:

Screenshot 2024-10-30 at 14 12 57

(what looks like one pixel difference at the top and at the bottom is probably due to content border and top highlight decoration)

@andy-goryachev-oracle
Copy link
Contributor

looking good:
Screenshot 2024-10-30 at 14 18 38

@andy-goryachev-oracle
Copy link
Contributor

Minor question: should the left/rightSystemInset include the rounded corners (see the screenshot on the right side):

Screenshot 2024-10-30 at 14 20 57

Probably not, the app code can account for that based on the platform.

@mstr2
Copy link
Collaborator Author

mstr2 commented Oct 31, 2024

Minor question: should the left/rightSystemInset include the rounded corners (see the screenshot on the right side):
Probably not, the app code can account for that based on the platform.

I agree. In addition to that, we also don't account for rounded corners in normal windows, they are just an implementation detail of the window manager.

@mstr2
Copy link
Collaborator Author

mstr2 commented Oct 31, 2024

no flicker on win11, thanks!

the height of the title bar is slightly off. I think it should be the same as the native title bar of DECORATED window.

This seems to be an artifact of different JavaFX/Windows rendering. If I make the title bar just one pixel taller, it is very slightly off in the other direction.

@tsayao
Copy link
Collaborator

tsayao commented Nov 4, 2024

image

I think it's fine, but is the window controls overlay supposed to take the whole window? I've set the background color just to demonstrate, it has no practical utility.

@tsayao
Copy link
Collaborator

tsayao commented Nov 4, 2024

I'm not sure if it's feasible, but having a GtkOverlay seems to work on a basic app paintable C app:

#include <gtk/gtk.h>

static gboolean on_draw_event(GtkWidget *widget, cairo_t *cr) {
    cairo_set_source_rgb(cr, 1.0, 0.0, 0.0);
    cairo_paint(cr);

    return FALSE;
}

static void create_overlay(GtkWidget *window) {
    GtkWidget *overlay;
    GtkWidget *hb;

    overlay = gtk_overlay_new();
    gtk_container_add(GTK_CONTAINER(window), overlay);

    hb = gtk_header_bar_new();
    gtk_header_bar_set_show_close_button(GTK_HEADER_BAR(hb), TRUE);
    gtk_header_bar_set_has_subtitle(GTK_HEADER_BAR(hb), FALSE);
    gtk_header_bar_set_custom_title(GTK_HEADER_BAR(hb), NULL);
    gtk_overlay_add_overlay(GTK_OVERLAY(overlay), hb);

    gtk_widget_set_valign(hb, GTK_ALIGN_START);
    gtk_widget_set_halign(hb, GTK_ALIGN_END);
}

int main(int argc, char *argv[]) {
    GtkWidget *window;

    // Initialize GTK
    gtk_init(&argc, &argv);

    GtkCssProvider *css_provider = gtk_css_provider_new();
    gtk_css_provider_load_from_data(css_provider,
        "headerbar {"
        "  background-color: rgba(255, 255, 255, 0.0);"
        "}",
        -1, NULL);

    gtk_style_context_add_provider_for_screen(gdk_screen_get_default(),
                                              GTK_STYLE_PROVIDER(css_provider),
                                              GTK_STYLE_PROVIDER_PRIORITY_USER);

    window = gtk_window_new(GTK_WINDOW_TOPLEVEL);
    gtk_window_set_title(GTK_WINDOW(window), "Test");
    gtk_window_set_decorated(GTK_WINDOW(window), FALSE);
    gtk_window_set_default_size(GTK_WINDOW(window), 400, 300);

    gtk_widget_set_app_paintable(window, TRUE);

    g_signal_connect(G_OBJECT(window), "draw", G_CALLBACK(on_draw_event), NULL);
    g_signal_connect(G_OBJECT(window), "destroy", G_CALLBACK(gtk_main_quit), NULL);
    create_overlay(window);
    gtk_widget_show_all(window);


    gtk_main();

    return 0;
}

image

Gtk4 even has WindowControls.

I started to play with the CSS to make it transparent, but it does not seem much straightforward, but possible.

Running the program with GTK_DEBUG=interactive makes it easier.

@andy-goryachev-oracle
Copy link
Contributor

Moving from one monitor to another with a different scale works as expected.

Opening the EXTENDED Stage with Scene.setNodeOrientation(RTL) produces expected result in terms of the native decorations:

Screenshot 2024-11-04 120500

[Unrelated] Curiously, setting Scene.setNodeOrientation(RTL) on an already open window (DECORATED) does not change the native decorations. I am not sure if this is a bug or works as expected, but in any case I don't care - seems to be a rather unlikely scenario.

@andy-goryachev-oracle
Copy link
Contributor

andy-goryachev-oracle commented Nov 4, 2024

There is, however, one problem in RTL mode on Win11:
something is wrong with the hover area of the native close ([x]) button. If I click on the center of the X, nothing happens, and it does not show the hover status. If I move the mouse pointer closer to the edge of the [x] button, the hover decoration comes on and the window can be closed.

Can you check please?

edit: even when the hover background is active, clicking on the button does not close the window, and double click maximizes the window.

Here is the recording:

video1943689320.mp4

Copy link
Contributor

@andy-goryachev-oracle andy-goryachev-oracle left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

first batch of comments up until and including HeaderBar.
to be continued...

"/DELAYLOAD:user32.dll", "/DELAYLOAD:urlmon.dll", "/DELAYLOAD:winmm.dll", "/DELAYLOAD:shell32.dll",
"/DELAYLOAD:Uiautomationcore.dll", "/DELAYLOAD:dwmapi.dll"]).flatten()
"/DELAYLOAD:Uiautomationcore.dll", "/DELAYLOAD:dwmapi.dll", "/DELAYLOAD:uxtheme.dll"]).flatten()
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minor suggestion: placing each entry on separate line might simplify maintenance and reduce merge conflicts.


/**
* Indicates that the window is modal which affects whether the window is minimizable.
*/
@Native public static final int MODAL = 1 << 9;
@Native public static final int MODAL = 1 << 10;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minor: would it be better to add EXTENDED after the MODAL to minimize the change? Do the actual values matter?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The values don't matter, as they are referred to with their constant name in native code. We could minimize the diff here, but then the "visual kind" flags wouldn't be grouped together...

@@ -254,6 +262,10 @@ protected Window(Window owner, Screen screen, int styleMask) {
throw new RuntimeException("The functional type should be NORMAL, POPUP, or UTILITY, but not a combination of these");
}

if ((styleMask & UNIFIED) != 0 && (styleMask & EXTENDED) != 0) {
throw new RuntimeException("UNIFIED and EXTENDED cannot be combined");
}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is it even possible to create a window with both UNIFIED and EXTENDED set?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, this is just a sanity check.

* </ul>
*
* <table style="white-space: nowrap">
* <caption>CSS properties of {@code window-button-container}</caption>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new CSS properties need to be included in cssref.html, along with the description of platform availability.

Should this be done as part of this PR? (that would be my preference)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

WindowControlsOverlay is not API, it's an implementation detail and as such must not be documented in cssref.html. This is by design: currently, this feature has a minimal API with just three new API elements: StageStyle.EXTENDED, HeaderBar, and HeaderBarBase. If we allowed app developers to customize window buttons, the API would explode in size and the specification burden would be immense. Let's not go there.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am confused. Can it be customized with a style sheet? If so, it should be documented, no?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It can't be customized by users, as there is no API for that. There wouldn't be a platform-independent way to do that, because we're not using WindowControlsOverlay on macOS in the first place.

* <tr><th>CSS property</th><th>Values</th><th>Default</th><th>Comment</th></tr>
* </thead>
* <tbody><tr>
* <th>-fx-button-order</th><td>&lt;integer&gt;</td><td>0/1/2</td>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what happens when CSS sets all buttons to the same value?
should this be something that user has control over vs. defined by the platform?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The buttons are sorted with List.sort, so that will dictate what happens in this scenario. Note that this class is not API, and neither users nor the platform will have any control over it.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

since it's still javadoc, I'll continue. The value is specified as 0/1/2 yet I can't see any validation of that (I suspect any value would work and be sorted as you mentioned). What gives?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Any value will work. This is the javadoc for buttonOrder:

    /**
     * Specifies the layout order of this button relative to the other buttons.
     * Buttons with a lower value are laid out before buttons with a higher value.
     * <p>
     * This property corresponds to the {@code -fx-button-order} CSS property.
     */

* @param x the X coordinate in physical pixels
* @param y the Y coordinate in physical pixels
*/
@SuppressWarnings("unused")
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tangentially related conversation starter:

should we have a couple of annotations for code called from JNI/native and reflection?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That may be a good idea, see my other comment.


@Override public String toString() {
View view = getPlatformView();
return (" scene: " + hashCode() + " @ (" + view.getWidth() + "," + view.getHeight() + ")");
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

leading space in toString() might be a bad idea

suggestion (JSON-like):

return "ViewScene" + hashCode() + "{width=" + view.getWidth() + ", height=" + view.getHeight() + "}";

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep, but this is existing code. The GitHub diff viewer makes it seem like it was changed, but it isn't.

/**
* Indicates that a system supports {@link javafx.stage.StageStyle#EXTENDED}.
* <p>
* This feature is currently supported on Windows, Linux, and macOS.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

would it make sense to add more information similarly to UNIFIED_WINDOW on L151?
maybe pointing to different levels of support?

I don't know whether it makes sense to bring the whole table from the JEP here, but maybe somewhere (HeaderBar)?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It links directly to StageStyle.EXTENDED, which contains lots of information. I don't think we need it here.

By the way, there are no support levels. The feature is supported in its entirety, as specified, on all desktop platforms. The table in the JEP is just informational to help OpenJFX developers understand what we're talking about. It's not a specification, and it can't be a specification because we either don't control things (for example, we have no influence on rounded corners, this could be changed with any future OS version) or because we'd be specifying us into a corner. There's no point prescribing every minute detail, and then being responsible to keep it working exactly as described, even though the semantics are unchanged.

The relevant parts are specified in StageStyle.EXTENDED and HeaderBar, and I wouldn't go further than this. We don't specify the details of StageStyle.DECORATED for each OS; why should we do it for StageStyle.EXTENDED?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess you are right here: from the app dev perspective, there is no difference between the supported platforms. All good.

I do suggest to bring a condensed version of the table in the JEP (or a simple

    here to show what's being painted by the platform and what is not. In other words, instead of reading 1k of text, I want to see a short list indicating that, for example, close button is painted by the platform, and the title bar is not painted.

    Can you do something like this? (Alternatively, there might be a better place to do that, but where?)

* All children will be resized to their preferred widths and extend the height of the {@code HeaderBar}.
* {@code HeaderBar} honors the minimum, preferred, and maximum sizes of its children. If the child's
* resizable range prevents it from be resized to fit within its position, it will be vertically centered
* relative to the available space; this alignment can be customized with a layout constraint.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what if the components are too large to fit, will clipping occur? should this behavior be mentioned?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The components can't be too large to fit:
{@code HeaderBar} honors the minimum, preferred, and maximum sizes of its children.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I want to know what happens when the layout is over-constrained. For example, consider the layout to have the leading, the center, and the trailing nodes set, and the leading one has minWidth set to 10_000. What happens?

Will the center and the trailing nodes be shown or clipped? will the layout attempt to squeeze all three to fit the available space?

Can I get this answer from the javadoc?

* {@link #trailingProperty() trailing}. {@code HeaderBar} ensures that the leading and trailing areas
* account for the default window buttons (minimize, maximize, close). If a child is configured to be
* centered in the {@code center} area, it is laid out with respect to the stage, and not with respect
* to the {@code center} area. This ensures that the child will appear centered in the stage regardless
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should there be more fine tuned control for growing/shrinking?

can the application just add a single container like GridPane that handles the resizing?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you mean with growing and shrinking?

An application can add a single GridPane to HeaderBar.center, and set its prefWidth to POSITIVE_INFINITY. This will extend the GridPane across the entire width of the header bar (excluding the window button area).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe what's needed is to borrow some text from the BorderPane, along the lines of

"The top and bottom children will be resized to their preferred heights and extend the width of the border pane. The left and right children will be resized to their preferred widths and extend the length between the top and bottom nodes. And the center node will be resized to fill the available space in the middle. Any of the positions may be null. "

the important parts are

  • how children are resized
  • any can be null

(the layout in the HB is like the one in the BorderPane, right?)

@mstr2
Copy link
Collaborator Author

mstr2 commented Nov 5, 2024

There is, however, one problem in RTL mode on Win11: something is wrong with the hover area of the native close ([x]) button. If I click on the center of the X, nothing happens, and it does not show the hover status. If I move the mouse pointer closer to the edge of the [x] button, the hover decoration comes on and the window can be closed.

Can you check please?

Thanks for discovering this, there was a problem with mirrored coordinates in RTL windows. Should be fixed now.

@mstr2
Copy link
Collaborator Author

mstr2 commented Nov 5, 2024

I think it's fine, but is the window controls overlay supposed to take the whole window? I've set the background color just to demonstrate, it has no practical utility.

Yes, the overlay is resizable and will always stretch the entire window. As you point out, there's no practical significance, as overlays are not part of the scene graph and applications will never be able to interact with them.

@mstr2
Copy link
Collaborator Author

mstr2 commented Nov 5, 2024

I'm not sure if it's feasible, but having a GtkOverlay seems to work on a basic app paintable C app:

Gtk4 even has WindowControls.

I started to play with the CSS to make it transparent, but it does not seem much straightforward, but possible.

Running the program with GTK_DEBUG=interactive makes it easier.

The main problem with this approach is that it presupposes that the drawing is only done in GTK callbacks. But that's not how JavaFX interacts with GTK, so I think it will probably not work. I haven't found a way to simultaneously use the current JavaFX rendering approach and mix in GTK widgets on the same surface.

@tsayao
Copy link
Collaborator

tsayao commented Nov 5, 2024

I'm not sure if it's feasible, but having a GtkOverlay seems to work on a basic app paintable C app:
Gtk4 even has WindowControls.
I started to play with the CSS to make it transparent, but it does not seem much straightforward, but possible.
Running the program with GTK_DEBUG=interactive makes it easier.

The main problem with this approach is that it presupposes that the drawing is only done in GTK callbacks. But that's not how JavaFX interacts with GTK, so I think it will probably not work. I haven't found a way to simultaneously use the current JavaFX rendering approach and mix in GTK widgets on the same surface.

Yeah, didn't work. In theory it should work with Wayland and a subsurface, like libdecor does. X11 has the concept of multiple stacked Windows, in theory it's possible, I just don't know how to sync it.

Copy link
Contributor

@andy-goryachev-oracle andy-goryachev-oracle left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

second batch of comments

/**
* Indicates that a system supports {@link javafx.stage.StageStyle#EXTENDED}.
* <p>
* This feature is currently supported on Windows, Linux, and macOS.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess you are right here: from the app dev perspective, there is no difference between the supported platforms. All good.

I do suggest to bring a condensed version of the table in the JEP (or a simple

    here to show what's being painted by the platform and what is not. In other words, instead of reading 1k of text, I want to see a short list indicating that, for example, close button is painted by the platform, and the title bar is not painted.

    Can you do something like this? (Alternatively, there might be a better place to do that, but where?)

* {@link #trailingProperty() trailing}. {@code HeaderBar} ensures that the leading and trailing areas
* account for the default window buttons (minimize, maximize, close). If a child is configured to be
* centered in the {@code center} area, it is laid out with respect to the stage, and not with respect
* to the {@code center} area. This ensures that the child will appear centered in the stage regardless
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe what's needed is to borrow some text from the BorderPane, along the lines of

"The top and bottom children will be resized to their preferred heights and extend the width of the border pane. The left and right children will be resized to their preferred widths and extend the length between the top and bottom nodes. And the center node will be resized to fill the available space in the middle. Any of the positions may be null. "

the important parts are

  • how children are resized
  • any can be null

(the layout in the HB is like the one in the BorderPane, right?)

* All children will be resized to their preferred widths and extend the height of the {@code HeaderBar}.
* {@code HeaderBar} honors the minimum, preferred, and maximum sizes of its children. If the child's
* resizable range prevents it from be resized to fit within its position, it will be vertically centered
* relative to the available space; this alignment can be customized with a layout constraint.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I want to know what happens when the layout is over-constrained. For example, consider the layout to have the leading, the center, and the trailing nodes set, and the leading one has minWidth set to 10_000. What happens?

Will the center and the trailing nodes be shown or clipped? will the layout attempt to squeeze all three to fit the available space?

Can I get this answer from the javadoc?

public class HeaderBar extends HeaderBarBase {

private static final String ALIGNMENT = "headerbar-alignment";
private static final String MARGIN = "headerbar-margin";
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Q: should these be a String or an Object? String.equals() are more expensive.

(I guess we use Strings elsewhere, so probably ok).

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

String literals are guaranteed to be interned by the Java Language Specification, so equals() is just a reference comparison.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good point.

public HeaderBar() {
// Inflate the minHeight property. This is important so that we can track whether a stylesheet or
// user code changes the property value before we set it to the height of the native title bar.
minHeightProperty();
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if that's the case, why not initialize it in L1150 ?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where? The file only has about 500 lines.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oops, my mistake. It's in Region!

@@ -1333,4 +1333,9 @@ - (GlassAccessible*)getAccessible
return (GlassAccessible*)jlong_to_ptr(accessible);
}

- (NSEvent*)lastEvent
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

could there be side effects with exposing this field?
concurrency issues?

* questions.
*/

.window-button-container {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is it possible for the app dev to alter the styling with an external style sheet?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, that's not possible. This part of the implementation is a black box. It's also what makes the feature easy to use for app developers: they don't need to concern themselves with window decorations on the various supported platforms, they can rest assured that it will just work.

}

.close-button > .glyph {
-fx-shape: "m 8.1464844,8.1464844 a 0.5,0.5 0 0 0 0,0.7070312 L 11.292969,12 8.1464844,15.146484 a 0.5,0.5 0 0 0 0,0.707032 0.5,0.5 0 0 0 0.7070312,0 L 12,12.707031 l 3.146484,3.146485 a 0.5,0.5 0 0 0 0.707032,0 0.5,0.5 0 0 0 0,-0.707032 L 12.707031,12 15.853516,8.8535156 a 0.5,0.5 0 0 0 0,-0.7070312 0.5,0.5 0 0 0 -0.707032,0 L 12,11.292969 8.8535156,8.1464844 a 0.5,0.5 0 0 0 -0.7070312,0 z";
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minor: we could probably minimize the path by rounding to 2 or 3 decimal points
(same comment for all .css changes)

}

.maximize-button.restore > .glyph {
-fx-shape: "m 7.6491699,2.5192871 q 0,-0.3444824 -0.1369629,-0.6495361 Q 7.3752441,1.5646973 7.1407471,1.338501 6.90625,1.1123047 6.5970459,0.98156738 6.2878418,0.85083008 5.9475098,0.85083008 H 1.7722168 Q 1.838623,0.65991211 1.9589844,0.50219727 2.0793457,0.34448242 2.2370605,0.23242188 2.3947754,0.12036133 2.5836182,0.06018066 2.7724609,0 2.9758301,0 H 5.9475098 Q 6.4746094,0 6.9394531,0.20129395 7.4042969,0.40258789 7.7508545,0.74707031 8.0974121,1.0915527 8.2987061,1.5563965 8.5,2.0212402 8.5,2.5483398 V 5.5241699 Q 8.5,5.7275391 8.4398193,5.9163818 8.3796387,6.1052246 8.2675781,6.2629395 8.1555176,6.4206543 7.9978027,6.5410156 7.8400879,6.661377 7.6491699,6.7277832 Z M 1.253418,8.5 Q 1.0043945,8.5 0.77612305,8.3983154 0.54785156,8.2966309 0.37561035,8.1243896 0.20336914,7.9521484 0.10168457,7.723877 0,7.4956055 0,7.246582 V 2.9550781 Q 0,2.7019043 0.10168457,2.475708 0.20336914,2.2495117 0.37561035,2.0772705 0.54785156,1.9050293 0.77404785,1.8033447 1.0002441,1.7016602 1.253418,1.7016602 h 4.2915039 q 0.2531738,0 0.4814453,0.1016845 0.2282715,0.1016846 0.3984375,0.2718506 0.170166,0.170166 0.2718506,0.3984375 0.1016845,0.2282715 0.1016845,0.4814453 V 7.246582 q 0,0.2531739 -0.1016845,0.4793701 Q 6.5949707,7.9521484 6.4227295,8.1243896 6.2504883,8.2966309 6.024292,8.3983154 5.7980957,8.5 5.5449219,8.5 Z M 5.5241699,7.6491699 q 0.087158,0 0.1639405,-0.033203 0.076782,-0.033203 0.1369628,-0.091309 0.060181,-0.058105 0.093384,-0.1348877 0.033203,-0.076782 0.033203,-0.1639404 v -4.25 q 0,-0.087158 -0.033203,-0.1660156 Q 5.8852539,2.730957 5.8271484,2.6728516 5.769043,2.6147461 5.6901855,2.581543 5.6113281,2.5483398 5.5241699,2.5483398 h -4.25 q -0.087158,0 -0.1639404,0.033203 -0.076782,0.033203 -0.1348877,0.093384 -0.0581055,0.060181 -0.0913086,0.1369628 -0.0332031,0.076782 -0.0332031,0.1639405 v 4.25 q 0,0.087158 0.0332031,0.1639404 0.0332031,0.076782 0.0913086,0.1348877 0.0581055,0.058105 0.1348877,0.091309 0.076782,0.033203 0.1639404,0.033203 z";
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

... especially here

"BOTTOM_LEFT, 10, 10, 100, 80",
"BOTTOM_CENTER, 10, 10, 100, 80",
"BOTTOM_RIGHT, 10, 10, 100, 80"
})
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

these tests can be simplified to avoid parsing with @CsvSource and default conversion, example:

    @ParameterizedTest
    @CsvSource(value = {"yo,true,1", 
                        "bah,true,1.1", 
                        "meh,false,2.2"})
    void test(String candidate, boolean expected, double a) {
        System.out.println("candidate=" + candidate + " expected=" + expected + " a=" +a );
    }

@andy-goryachev-oracle
Copy link
Contributor

please link your JEP from this PR

@mstr2
Copy link
Collaborator Author

mstr2 commented Nov 5, 2024

Yeah, didn't work. In theory it should work with Wayland and a subsurface, like libdecor does. X11 has the concept of multiple stacked Windows, in theory it's possible, I just don't know how to sync it.

I like the idea of having different subsurfaces for JavaFX client-side rendering and window decorations. We'd need a working Wayland backend, though...

@@ -275,30 +234,25 @@ void alignmentOfCenterChild_resizable_withNonEmptyLeadingAndTrailingChild(String
"BOTTOM_CENTER, 450, 40, 100, 50",
"BOTTOM_RIGHT, 740, 40, 100, 50"
})
void alignmentOfCenterChild_notResizable_withNonEmptyLeadingAndTrailingChild(String arg) {
String[] args = arg.split(",");
void alignmentOfCenterChild_notResizable_withNonEmptyLeadingAndTrailingChild(
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minor suggestion:

long test names do not help much (and actually may cause problems, see https://bugs.openjdk.org/browse/JDK-8334497)

also rather inconvenient to see in the logs, or IDEs. You can use comments for human-readability and short(er) method names.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
csr Need approved CSR to integrate pull request rfr Ready for review
Development

Successfully merging this pull request may close these issues.

5 participants