Style themes API

[Michael Strauß]

On Thu, Feb 2, 2023 at 12:14 AM Pedro Duque Vieira
<pedro.duquevieira at gmail.com> wrote:
> The fact that a theme is either dark or light is strongly correlated to whether you as a developer want all window decorations to be light or dark. I'd say that very few use cases will want to have some windows to be light and others to be dark.
> As such, this API as it is, will force developers to set the window decorations to either light or dark every time they spawn a new Window (spawning a separate Window, a Dialog, etc). I'd say it would be a good idea to set the window decorations based on what is defined in the StyleTheme with the possibility to override them if you set it on the Window itself.

I've thought a bit about how we could have such a feature without
introducing Stage appearance to the StyleTheme interface (I think the
two concepts should remain separate).
Here's the updated design document with a proposal:
https://gist.github.com/mstr2/9f46f92c98d3c86aa6a0b4224a9a6548#changing-the-default-stage-appearance
What do you think? I'm not entirely convinced that the added
complexity is worth the benefit that this feature brings.



> Looking at the doc you created. Some comments:
> - I like the Preferences API
> - "Appearance" or "ThemeAppearance"? "Appearance" sounds like a rather generic term that could mean anything..
> - perhaps rename the Stage appearance property to something like: "frameDecorations", e.g. "setFrameDecorations(Appearance)"?

I like the term "appearance" precisely because it's rather generic.
Apple also likes to call it like that, so there's some precedent for
it.



> - " A future enhancement may refactor the built-in themes to make color definitions swappable". This is already possible. Modena has its color definitions given by css variables which can be easily overridden in CSS. That's also a strong part of how I currently switch JMetro to either dark or light version without having to duplicate every style definition. Side note: JMetro is composed of several stylesheets (more than 1) so it would be a nightmare or impossible to make JMetro be a user agent stylesheet with the current state of the JavaFX API (+1 for this new API :-) ).
> - Perhaps rename "Application.userAgentStylesheetXX" to  "Application.styleThemeXX" and keep the semantics? If we make it be "userAgentStylesheetXX" it means we can no longer in a future version make StyleTheme have a property to define whether they are to be user agent stylesheets or author stylesheets. It gives less room for us to be able to change our minds in the future.

If we have, at some point in the future, both a
`Application.userAgentStyleTheme` and `Application.styleTheme`
property, then users can decide whether they want the style theme to
have user-agent semantics, or author semantics.
Or do you want an option for style themes to decide for each indiviual
stylesheet whether it should have user-agent or author semantics?



> - Perhaps instead of the section "Goals" being named "Goals" we could name it "Advantages of this API" or something along those lines and have it be the first topic. I think the first question people will ask is: "what's the advantage of this new feature?".. so I think it would be nice if it's the first topic so that we grab people's attention from the start.
> - instead of "Promote CSS user-agent themes from an implementation detail to a first-class concept.", perhaps something more clear? Something like: "Allow easier creation of themes that are composed of user agent stylesheets (like Modena and Caspian). These themes may be composed of more than 1 user agent stylesheet which isn't possible with the current javafx API". Also perhaps make reference to the fact that 90% (rough estimate) of themes out there are composed of author style sheets and it's difficult for them to be different, which can be problematic for users of those themes: styles set in code will be overridden, styles set in FXML, styles set in author stylesheets created by the developers if the specificity of those styles is lower than the themes styles..

I've roughly followed the JEP format with this enhancement proposal.
Added a clarification like you suggested to the Goals section.