On Tue, 14 Jul 2026 15:34:55 GMT, Martin Fox <[email protected]> wrote:
> > My main point is that `StageBackdrop` is quite closely related to `Paint`,
> > which are shareable configuration objects created by users, and should
> > therefore have a similar API.
>
> And Paints are immutable by design.
True, it's not a perfect analogy.
> And you're again arguing based on your notion of API consistency and not
> utility. With your proposed API this call:
>
> ```
> stage.getBackdrop().setOption("TintColor", Color.RED);
> ```
>
> could change the tint color for multiple stages. Now that, that is unusual in
> the JavaFX API. And I think unexpected. Will developers consider this useful
> or behavior that they have to work around?
You think this is unexpected; I think this is exactly what should happen (and
what I'd intuitively think _would_ happen based on how Java generally works for
indentity objects). If I share an object instance, then I expect changes to the
object state be visible across all use sites. For example, if I had a global
backdrop object, and I'd set it on every stage I create, then I'd also expect
all stages to react when I change its configuration. I think I'd consider this
a feature, not a bug.
> > Preferences are the user's choice (compared to the developer's choice when
> > building the app), and should ideally be respected out of the box, without
> > requiring developers to "opt in" by branching over preferences (setting a
> > backdrop when reducedTransparency=false, and not setting a backdrop
> > otherwise).
>
> Again, I'm not that familiar with this API. The OS level setting for
> "reducedTransparency" is clearly the user's choice. I'm less clear on what it
> means to override the OS setting at the Scene level.
Overriding preferences at the Scene level is meant to give applications the
capability to give users choice, for example by choosing a color scheme that's
different from the OS. Applications could want to do this for a number of
reasons: their UI could simply not be optimized for dark mode, or they might
use legacy controls (maybe Swing controls) without a good dark mode
integration. Other applications may simply want to allow users to choose the
color scheme for just this application, which is generally a good idea because
some users prefer to have individual applications with a color scheme different
from the OS.
In this example, an application won't magically adapt by just changing the
color scheme at the Scene level. This requires themes that actually offer
distinct light/dark modes. Neither Caspian nor Modena do this, but future
themes will (we've recently added CSS media queries just for this purpose).
So what does it mean to override OS preferences? It means that the theme and/or
the application consult these preferences for their styling decisions, such
that the preference is meaningfully reflected in the user experience. In
another example, we recently had control-level animations consult the
reducedMotion preference before playing. In yet another example, we've had the
system-decorated title bar (the one you'll get with a `StageStyle.DECORATED`
window) change its appearance based on the Scene color scheme. All of this
works out of the box (as will a future theme with dark mode support).
The last example, where the system-decorated title bar adapts to the Scene
color scheme, is quite comparable to a window backdrop. We tell the OS to
change something under its control based on Scene-local user preference. So in
the ideal case, I'd also want the same thing to happen for backdrops: when our
window is in light mode, then we get the light backdrop. If it has reduced
transparency, the backdrop won't be translucent. The question is how much of
that is realistically achievable.
Let's just for a moment think about what happens if the window backdrop is
completely decoupled from Scene preferences. If a theme supports both light and
dark mode, and an application allows users to switch color schemes, this would
mean that a user trying to have a light application color scheme on a dark OS
scheme would most likely have a bad experience when the window uses a backdrop
(because that implies dark text on a dark background).
> The OS backdrop selects a background color based on the window's state and
> various preferences and draws that beneath the Scene's fill color. This is
> the behavior that developers will have to design for and test against. For
> example, clients of the backdrop API will automatically be exposed to the to
> high and low contrast mode settings.
>
> To honor a reduced transparency override we'll need to disable the OS
> backdrop which will also throw away its drawing of a background color. That
> will need to be replaced.
>
> I've given this some thought. I was considering making backdrops
> "cross-platform" by emulating the background color drawing behavior on
> platforms that don't support backdrops natively. Because, again, the
> translucency is really beside the point in terms of development and testing.
> Win11 barely has any translucency.
>
> So it's not just a question of reduced transparency. What does it mean for a
> client to override the system's background color in the Scene settings? In
> theory this should also mean disabling the OS backdrop since it can't honor
> that setting. It's not a question of how to choose a background color, it's a
> question of when we want to disable the OS backdrop. Whenever the client has
> overriding reducedTransparency? Whenever the client has overridden the
> Scene's background color? Whenever the window's color scheme doesn't match
> the platform's color scheme (at which point the OS will draw a background
> color that doesn't match the global background color preference)? Under these
> conditions either JavaFX needs to figure out the background color or we need
> to provide guidance to developers on what to do.
Well, it comes down to that, doesn't it? Either we come up with something, or
we provide guidance to avoid the worst pitfalls. That being said, I'd really
like it if the backdrop would at least be shown in the Scene's color scheme.
But that doesn't seem to be possible on Windows with the
`DWMWA_SYSTEMBACKDROP_TYPE` approach, it seems it would require using
`MicaController` from the Windows App SDK. I'm not sure if we can depend on
that.
-------------
PR Comment: https://git.openjdk.org/jfx/pull/2048#issuecomment-4972114813
