Style themes API

[Michael Strauß]

Hi Pedro,

please see my comments below:


On Fri, Jan 13, 2023 at 10:06 PM Pedro Duque Vieira <duke at openjdk.org> wrote:
>
> Hi all,
>
> I’ve seen in the mailing list a request for commenting on this PR and as a long-time theme developer (JMetro and other themes) I'd thought I'd give my 2 cents.
>
> I think it’s a good idea to add the concept of a theme to the JavaFX API! So, thanks for this.
>
> 1 - Reading through the javadocs in this PR and the description, I think it’s not clear whether the stylesheets of a StyleTheme will be used as user agent stylesheets or as author stylesheets. It says that StyleThemes have higher precedence than a user agent stylesheet so I suppose they are going to be author stylesheets (?), but there’s no point in the Javadoc where that is explicitly said. If that’s not the case, then I think the opposite should then be explicitly written. I.e. that it will have higher precedence than a user agent stylesheet but it’s not an author stylesheet.


Theme stylesheets have a higher precedence than the application's
user-agent stylesheet, but a lower precedence than author stylesheets.
This is stated in the JavaFX CSS reference (cssref.html):

    * The JavaFX CSS implementation applies the following
    * order of precedence: a style from a user agent style sheet or a
style theme has lower
    * priority than a value set from code, which has lower priority than a Scene
    * or Parent style sheet.

We could include similar language in the javadoc.



> 2 – I think the ability to specify in the StyleTheme whether it is a user agent stylesheet, or an author stylesheet could be of interest. Most of the themes I know are composed of author stylesheets (they use the getStylesheets() API in Scene) so migration to using the StyleTheme API would be easier if one could specify this. Conversely specifying that the StyleTheme is a user agent stylesheet will also be very useful in the cases where we’re creating a theme but don’t want it to override styles specified through code, etc.


I deliberately wanted to minimize changes to the CSS subsystem in
order to prevent introducing regressions in that area of the codebase.
As a result, the proposed implementation treats theme stylesheets as a
list of user-agent stylesheets, and optionally adds the application's
user-agent stylesheet as the first item in that list. Note that
`javafx.css.StyleOrigin` is also unchanged; you won't know whether a
`StyleOrigin.USER_AGENT` stylesheet is the application's user-agent
stylesheet, or one of its theme stylesheets.



> 3 – I would really love for JavaFX to have first class support for dark and light modes, and I think this would be the ideal place for it.  One of the problems with how things are right now is that if you create a dark theme with this API or the previous API (using stylesheets) the frames of windows (main windows and dialogs) will still show with a light theme (I see this on Windows, haven’t tested on Mac but I suppose it will be the same).
> So as it is, you can’t fully create a dark theme in JavaFX. The only way would be to call on native code to change the frame of windows (by making a request for the native window to change its appearance to dark mode) which isn’t trivial and would have to be done for the various operating systems and it’s subject to break.
> The other way would be to create your own frames of the windows which I think would be even worse. You’d have to create the frame buttons yourself and all other decorations. If they don’t visually exactly match the ones from the native platform they’re going to look off. You’d also have to do this for all operating systems and for their various versions (various versions of the same OS might have different frame decorations, e.g. win10 vs win11).
> Given that dark and light theme concepts are pervasive across all major operating systems (Windows, Mac, iOS, Android, etc) and it’s a concept that has lasted for years and continues to exist, I think it would be of value to fully support this.

There's a role for third-party libraries here, and I think APIs for
dark/light mode and other things can be done there.
Supporting dark/light window frames is quite independent from the
proposed style theme API, and should be done in a separate PR.
I understand that it might be nice to have a comprehensive dark/light
mode API in JavaFX, but there's a value in not going there and leaving
that to libraries instead. I'd rather keep this feature as simple as
it gets without sacrificing its unique capabilities. We can always
come back and add more API surface if it turns out that we're really
missing something.