On Thu, 9 Jul 2026 03:17:00 GMT, Michael Strauß <[email protected]> wrote:
> I think the main point of tension in the API is that we have two seemingly > different forms of backdrops: > > 1. Constant backdrops: `WINDOW` and `PARTIAL`, which are exposed as static > fields. > 2. Configurable backdrops, which include dynamic parameters that can change > at runtime. This PR assumes that any backdrop can have dynamic parameters, including WINDOW and PARTIAL. The API for setting options is the same for all styles so we can easily add dynamic parameters to the standard backdrop styles in the future. > I think there shouldn't be two API elements to configure a single aspect > about the `Stage`, it should be a single API element. Instead, move the > complexity from `Stage` to `StageBackdrop`. This raises the possibility that a client could take the option-setting object (the StageBackdrop) and assign it to multiple stages. We could: 1. Allow it; when an option changes all of the stages that reference that StageBackdrop get updated. I don’t think it’s intuitive or useful to share options across stages and it would complicate the implementation and testing. 2. Prevent it; force the user to create a new StageBackdrop instance for each stage. We would be forcing clients to create multiple objects to support a feature (per-stage option setting) most of them won't even use. With the API in this PR the vast majority of calls will be either `initBackdropStyle(StageBackdropStyle.WINDOW)` or `initBackdropStyle(StageBackdropStyle.PARTIAL)` which mirror the existing API calls for setting the StageStyle. I'm hoping most clients won't use the platform-specific styles and I doubt they'll have much use for the options API. The only style which takes options is a novelty (macOS.ClearGlass) and I don't see that changing anytime soon. > In this example, the API forces callers to provide a fallback backdrop in > case the named backdrop is not available. This ensures that developers don't > need to worry about `null`: I think clients would rather develop their own fallback strategies. > Looking forward, we'll want to also support translucent backdrops on Linux at > some point in the future. With GTK4/Wayland, we could use > [ext-background-effect-v1](https://wayland.app/protocols/ext-background-effect-v1#ext_background_effect_surface_v1:request:set_blur_region) > to achieve that, which says: "The blur algorithm is subject to compositor > policies." I'm bringing this up because platform implementations might not > only allow developers to use _more_ types of backdrops, but also come with > restrictions that allow no choice at all: In this case, there would be no > difference between `WINDOW` and `PARTIAL` on Linux. Maybe this means our API > should only have a single default backdrop, and for all other backdrops, > you'd use platform-specific names? Mac and Windows take the same approach for specifying a backdrop: you describe the type of content you’re displaying and the OS picks an appropriate visual. At the API level there’s not one style per visual effect, there’s one style per content type. It’s possible that some content types share the same visual effect but that may change in a future OS release. I’m inclined to take the same approach for the JavaFX API so it doesn’t matter if WINDOW and PARTIAL aren’t visually distinct on all platforms. > Another aspect we should consider is the interaction with > `Scene.Preferences.reducedTransparency`: This preference can be toggled at > runtime, potentially by users of the application. Should it have an effect on > a potential translucent window background? With the exception of macOS.ClearGlass all of the existing backdrops interact with the window’s color scheme, activation state, and multiple platform preferences. We don't have control over any of this. Reduced transparency is the easiest; it removes translucency but doesn’t have much effect on the background color. The accessibility contrast modes do change the background color. In the end the assumption is that backdrops draw using a background color similar to `PlatformPreferences.backgroundColor` and so all text should be drawn using `PlatformPreferences.foregroundColor`. This is about all we can guarantee about the standard backdrops. This will complicate the implementation on Linux. I suspect the Wayland extension will only handle blurring and it will be up to us to track the platform preferences to get WINDOW and PARTIAL to behave the same way they do on Mac and Windows. ------------- PR Comment: https://git.openjdk.org/jfx/pull/2048#issuecomment-4938040935
