On Fri, 10 Jul 2026 17:50:16 GMT, Martin Fox <[email protected]> wrote:
> 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. The closest thing to `StageBackdrop` is `Paint`: it's a configurable object that describes some visual appearance. Most paints are immutable, but `ImagePattern` is mutable when it represents an animated image. Paints are reusable within a scene and across multiple scenes, so when you say sharing configuration objects is neither intuitive nor useful, you're arguing against prior art. I'm also not sure what to make of your presented arguments: implementation and testing difficulty shouldn't be the main driving force behind API design (they _can_ be major considerations, but grounding an API shape in those considerations should require a high bar of justification). Similarly, "forcing clients to create multiple objects" seems like a pretty neutral statement to me; by itself it's not a great argument in favor or against any particular API shape. Because `StageBackdrop` is `Paint` are so similar, I've experimented at one point to have `BackdropBlur extends Paint` that, when applied to the scene background, would enable the backdrop blur effect for the window (and by extension, when applied to a region within the JavaFX scene graph, would enable a similar effect within the scene graph). In the end, I've come to the conclusion that `StageBackdrop` is sufficiently dissimilar from the other paint types that it shouldn't be an actual `Paint`. However, I still think that the similarity that undoubtedly exists should result in similar patterns of use. This is compounded by my observation that your proposed API (_you_ say which type of thing you want to have, and _JavaFX_ creates another type of configuration object for you internally) doesn't seem to fit in with existing JavaFX patterns. I'm not ready to "disagree and commit" to your proposal, but I hope that other people will join the discussion to move it forward. > > 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. Sounds reasonable. However, you're exposing `null` to callers in an indirect way. It's one thing to have a pair of `initBackdrop(StageBackdrop)` and `getBackdrop() -> StageBackdrop`, where the getter returns whatever you pass into the setter; and if you pass `null` into the setter, you'll also receive `null` from the getter. Another thing entirely is what you are proposing: you call `initBackdropStyle(StageBackdropStyle)`, and the return value of `getBackdrop() -> StageBackdrop` is now either `null` or an object you didn't create. > 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. Sounds reasonable. > 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. I understand that when we use a platform-provided backdrop, the "reduce transparency" OS setting will be automatically applied. In my scenario, the OS-level setting is not enabled, but `Scene.Preferences.reducedTransparency` is. This is a completely supported scenario in JavaFX, with the implication that well-behaved applications will respect the setting and reduce their use of transparency. My question is what we should do about the transparent background in this case. It won't be made non-transparent by the OS automatically, because the OS-level "reduced transparency" setting is not enabled. Still I think we should, where possible, respect the JavaFX-level setting and remove the transparent backdrop material. ------------- PR Comment: https://git.openjdk.org/jfx/pull/2048#issuecomment-4939242532
