Style themes API

Wed Feb 1 23:14:09 UTC 2023

>
> 1) Ease of migration should be an important consideration, but there
> are also other considerations. I'd argue that getting the feature
> stacking and mental model right is more important, and giving themes a
> way to individually select if the stylesheets are user-agent or user
> stylesheets makes it hard to understand why my locally-set property
> value is being ignored by JavaFX in one theme, but not in the other.

2) The scenario you describe occurs when an application sets the value
> of styleable properties from code, but the values are overridden by an
> author stylesheet. Yes, that might happen, and I think it's up to the
> application developers to fix that. The reason why I think we should
> only support `Application.userAgentStyleTheme` in the first version of
> this new feature is quite simple: I'd rather have the feature actually
> make it into JavaFX than be stuck in review because it's too large and
> too complex of a change. User-agent style themes are pretty easy to
> implement (most of the code is already in place), while author style
> themes are not. We can add author style themes as a follow-up
> enhancement.

Author stylesheets are an inherent feature of JavaFX. It's already a
feature that exists so I think developers shouldn't be surprised if author
stylesheets override their styles set in code.
But anyways, you've convinced me on making this just be a user agent
stylesheet for now. Like you say, that way this feature doesn't get too
large and we're able to ship it quicker. :-)

 I'll point you to this document, which describes the latest version of
> this feature:
> https://gist.github.com/mstr2/9f46f92c98d3c86aa6a0b4224a9a6548
> What do you think about the interaction between the various parts of
> the new API, especially in regards to the appearance of native
> platform decorations?
> I'm not convinced that it is a good idea to make either `StyleTheme`
> or `Stage.appearance` more complicated by automatically inferring the
> value of one from the other.

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.

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)"?
- " 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.
- 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..

On Wed, Feb 1, 2023 at 12:22 AM Michael Strauß <michaelstrau2 at gmail.com>
wrote:

> On Tue, Jan 31, 2023 at 6:14 PM Pedro Duque Vieira
> <pedro.duquevieira at gmail.com> wrote:
> > Thinking of existing themes migrating to this StyleTheme API (90% are
> implemented as author stylesheets), some visual glitches may start
> appearing for users of those themes once they start using the migrated
> versions (since they will go from being author stylesheets to user agent
> stylesheets).
> > So, 2 things to think about:
> > 2.1 - How important is it that we think about this use case: existing
> themes migrating to this new API. I'd say we should probably think about it
> when designing this new API.
> > 2.2 - The second thing then is, how problematic will it be for
> programmers using these themes to have their apps start having visual
> glitches because of these themes changing from author stylesheets to user
> agent style sheets?
> > Perhaps we simply don't bother with this last point and simply have it
> be the price of innovation. And so programmers will have to adapt their
> applications and remove any code that is overriding the styles defined in
> the StyleThemes (which are likely causing these visual glitches when
> migrating to Themes using this new StyleTheme API). The same for any styles
> already defined in custom author stylesheets that are being used by the
> application and that might be NOW overriding the styles of the theme.
>
> 1) Ease of migration should be an important consideration, but there
> are also other considerations. I'd argue that getting the feature
> stacking and mental model right is more important, and giving themes a
> way to individually select if the stylesheets are user-agent or user
> stylesheets makes it hard to understand why my locally-set property
> value is being ignored by JavaFX in one theme, but not in the other.
>
> 2) The scenario you describe occurs when an application sets the value
> of styleable properties from code, but the values are overridden by an
> author stylesheet. Yes, that might happen, and I think it's up to the
> application developers to fix that. The reason why I think we should
> only support `Application.userAgentStyleTheme` in the first version of
> this new feature is quite simple: I'd rather have the feature actually
> make it into JavaFX than be stuck in review because it's too large and
> too complex of a change. User-agent style themes are pretty easy to
> implement (most of the code is already in place), while author style
> themes are not. We can add author style themes as a follow-up
> enhancement.
>
>
>
> > I don't think we should put having StyleTheme be just a collection of
> stylesheets and nothing else as a requirement. I'd rather think of
> StyleTheme as being the concept of a Theme and all the possible properties
> and definitions of what a Theme is. This is one of the strengths of this
> new feature you've proposed, i.e.
> > having the concept of a Theme exist in JavaFX whereas in the past there
> was no such concept and a "Theme" was just a collection of stylesheets.
> Added through the getStylesheets() method or through the
> setUserAgentStylesheet method.
> >
> > I'll just note that we don't just want the applications to be light or
> dark depending on what is set in the Operating System. You'll also want the
> ability to set whether the app is in dark or light mode on a per
> application level irrespective of what is defined in the OS (this already
> happens on many existing applications out there). So I think that
> DarkModeAware interface would have to have a method like:
> >   ThemeMode getMode();
> > Where ThemeMode can either be LIGHT, DARK or OS_DEFINED (I've named it
> ThemeMode just as an example).
> >
> > So I think we could do it in 2 ways: one way would be to do it as you
> say (though DarkModeAware interface would need the getMode() method that I
> suggested, I think) or add a method in the StyleTheme interface itself in a
> future release:
> >   ThemeMode getMode();
> > That method would probably need to have a default implementation that
> simply returns LIGHT because of retro compatibility.
> >
> > So, ThemeMode could be one of 3 possible values: LIGHT, DARK or
> OS_DEFINED. Where OS_DEFINED means that the app will honor whatever is
> defined at the OS level.
> > JavaFX Window decorations would need to respect whatever is returned in
> this getMode() method and change their decorations to either LIGHT or DARK
> depending on its value. This would also remove the need for boilerplate
> code that for every Window that is created sets it to be LIGHT or DARK
> depending on whether the Theme is LIGHT or DARK.
> >
> > Of course, we can also simply support this from the get go and have this
> method exist in StyleTheme from the start.
>
> I'll point you to this document, which describes the latest version of
> this feature:
> https://gist.github.com/mstr2/9f46f92c98d3c86aa6a0b4224a9a6548
> What do you think about the interaction between the various parts of
> the new API, especially in regards to the appearance of native
> platform decorations?
> I'm not convinced that it is a good idea to make either `StyleTheme`
> or `Stage.appearance` more complicated by automatically inferring the
> value of one from the other.
>

-- 
Pedro Duque Vieira - https://www.pixelduke.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/openjfx-dev/attachments/20230201/edbd7458/attachment.htm>