Re: Style themes API
(I made a mistake and only replied to you, resending this email to the mailing list and you) > 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. Thanks for proposing a new API. I really still think "appearance" should be part of the StyleTheme and I find that API, in the proposal, to be somewhat too complex. :-) I think at the base of our disagreement is that we have 2 distinct opinions of what a StyleTheme is. I see it as the concept of a theme and so anything that defines a theme should go in there (my opinion). Correct me if I'm wrong but you view StyleTheme as a collection of Stylesheets and nothing else. But then what's the advantage of it being just a collection of Stylesheets, why should we have that requirement, what do we gain with it? And why not call it StylesheetCollection instead (or something like that)? Or perhaps we could do it without introducing a new interface since it's just a collection of Stylesheet objects. I still think we should have the StyleTheme interface and my main points to having appearance be in StyleTheme is that: 1 - A theme being either dark or light is part of what a theme is. 2 - 99% of use cases are going to want to have all Windows (Dialogs, Windows, etc) to have either a light or dark appearance and I think we should make that easy to do, whereas with this API we make it more difficult since we force the developer to set the appearance on every Window he creates (plus the possibility of setting one of the windows to the wrong appearance). BTW, I'm not saying we can't have an appearance property in the Window (I think we should have it) but I'm also saying we should have appearance be in StyleTheme. I believe that a good API makes the more common use cases easier to do (and code) and so we should make it easy for developers to switch all Windows to either dark or light 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. Ok that makes sense. If there's a precedent of Apple calling it appearance then we can adopt that! > 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? I would prefer an option in StyleTheme that says whether it's a user agent stylesheet or author stylesheet.. but my main point is, if we don't name it userAgentStylesheet we can, in the future, either do as you say or do as I say. It'll leave room for us to change our mind. I've roughly followed the JEP format with this enhancement proposal. > Added a clarification like you suggested to the Goals section. Sounds good! Thanks again, On Thu, Feb 2, 2023 at 8:42 AM Michael Strauß wrote: > On Thu, Feb 2, 2023 at 12:14 AM Pedro Duque Vieira > 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
Re: Style themes API
On Thu, Feb 2, 2023 at 12:14 AM Pedro Duque Vieira 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.
Re: Style themes API
> > 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
Re: Style themes API
On Tue, Jan 31, 2023 at 6:14 PM Pedro Duque Vieira 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
Re: Style themes API
My previous message seems to have perhaps gotten lost in the various messages exchanged in this mailing list.. (just doing this small comment so that my previous message doesn't get lost..) It's getting very late here where I live, I will be back later tomorrow (a few hours from now). Thanks On Tue, Jan 31, 2023 at 5:14 PM Pedro Duque Vieira < pedro.duquevie...@gmail.com> wrote: > Hi Michael, > > Truly sorry for the late reply but haven't had time to reply sooner, > unfortunately.. > > 2 - > >> > I've been building javafx themes for years now. Started creating JMetro >> in JavaFX version 2. During this time I've been following how other themes >> are being built and I can say that about 90% of the themes (rough estimate) >> that are out there, are composed of author stylesheets, i.e they override >> values set from code (including JMetro). >> > I agree that themes that are to be provided to other developers would >> probably be better off if they are user agent stylesheets. My point is that >> migrating those 90% of themes to use this API would be easier if this flag >> exists otherwise migration would likely introduce UI regressions for >> developers using those themes. >> > >> > To be clear, what I'm proposing is a flag, or enum, or whatever, in >> StyleTheme that defines whether the stylesheets in the StyleTheme should be >> a user agent stylesheet or author stylesheet. >> > >> > Another point is in making themes that are only to be used locally in a >> specific app that the developer is creating. It might be of interest that >> he can toggle this flag and make all settings defined in the theme override >> any styling set from code (or in FXML) so that he can have a centralized >> point where all styling is done. > > > I think that the likelihood of this feature making it into the 21 >> release dramatically increases if we keep changes to the CSS subsystem >> to an absolute minimum. I understand your point, but I want to deliver >> this feature in the smallest useful package and add more features >> later with follow-on PRs. > > > That's why I've renamed `Application.styleTheme` to >> `Application.userAgentStyleTheme`. This makes it unmistakably clear >> that we're only talking about user-agent stylesheets. >> Also, it leaves open the possibility to add the >> `Application.styleTheme` property later, which would cause the theme >> to be interpreted as comprised of author stylesheets. >> Classifying author/UA themes at the property level is also more >> consistent with the way author/UA stylesheets are currently classified >> in JavaFX. >> What do you think about the styleTheme/userAgentStyleTheme API, >> instead of having a flag in the implementation of StyleTheme itself? > > > Since one of the objectives of the PR is to promote Caspian and Modena >> to first-class theme implementations, it makes sense to focus on UA >> themes first (since built-in themes are comprised of UA stylesheets). > > > OK. > 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. > > > 3 - > > Style themes are generally either defined as dark or light. i.e. you'll > very rarely have a theme that has some Windows with dark decorations and > others with light decorations. So I think it makes sense to have this as a > theme property. > > The ability to toggle decorations (light or dark) on an individual > Window is a good point you're making. Perhaps we should have a global > definition in the StyleTheme (whether the theme is light or dark) and a > definition that can be set per Window. > > If you set it on the StyleTheme then all Windows will respect it, but > you can override that value on each Window. If you override it on a > specific Window, that definition would take precedence over the global > StyleTheme one. > > In general,
Re: Style themes API
Hi Michael,
Truly sorry for the late reply but haven't had time to reply sooner,
unfortunately..
2 -
> > I've been building javafx themes for years now. Started creating JMetro
> in JavaFX version 2. During this time I've been following how other themes
> are being built and I can say that about 90% of the themes (rough estimate)
> that are out there, are composed of author stylesheets, i.e they override
> values set from code (including JMetro).
> > I agree that themes that are to be provided to other developers would
> probably be better off if they are user agent stylesheets. My point is that
> migrating those 90% of themes to use this API would be easier if this flag
> exists otherwise migration would likely introduce UI regressions for
> developers using those themes.
> >
> > To be clear, what I'm proposing is a flag, or enum, or whatever, in
> StyleTheme that defines whether the stylesheets in the StyleTheme should be
> a user agent stylesheet or author stylesheet.
> >
> > Another point is in making themes that are only to be used locally in a
> specific app that the developer is creating. It might be of interest that
> he can toggle this flag and make all settings defined in the theme override
> any styling set from code (or in FXML) so that he can have a centralized
> point where all styling is done.
I think that the likelihood of this feature making it into the 21
> release dramatically increases if we keep changes to the CSS subsystem
> to an absolute minimum. I understand your point, but I want to deliver
> this feature in the smallest useful package and add more features
> later with follow-on PRs.
That's why I've renamed `Application.styleTheme` to
> `Application.userAgentStyleTheme`. This makes it unmistakably clear
> that we're only talking about user-agent stylesheets.
> Also, it leaves open the possibility to add the
> `Application.styleTheme` property later, which would cause the theme
> to be interpreted as comprised of author stylesheets.
> Classifying author/UA themes at the property level is also more
> consistent with the way author/UA stylesheets are currently classified
> in JavaFX.
> What do you think about the styleTheme/userAgentStyleTheme API,
> instead of having a flag in the implementation of StyleTheme itself?
Since one of the objectives of the PR is to promote Caspian and Modena
> to first-class theme implementations, it makes sense to focus on UA
> themes first (since built-in themes are comprised of UA stylesheets).
OK.
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.
3 -
> Style themes are generally either defined as dark or light. i.e. you'll
very rarely have a theme that has some Windows with dark decorations and
others with light decorations. So I think it makes sense to have this as a
theme property.
> The ability to toggle decorations (light or dark) on an individual Window
is a good point you're making. Perhaps we should have a global definition
in the StyleTheme (whether the theme is light or dark) and a definition
that can be set per Window.
> If you set it on the StyleTheme then all Windows will respect it, but you
can override that value on each Window. If you override it on a specific
Window, that definition would take precedence over the global StyleTheme
one.
In general, StyleTheme is a very simple concept: it's a dynamic
> collection of stylesheets.
> I don't think the interface should force implementers to deal with
> anything other than stylesheets. If we did that, the following code
> wouldn't work any more:
Application.setUserAgentStyleTheme(
> () -> List.of("stylesheet1.css", "stylesheet2.css");
Maybe we can add a new interface, for example DarkModeAware, and if an
> application theme is marked with this interface, JavaFX will try to
> respect dark/light mode for
Re: [External] : Re: Style themes API
Hi Andy,
see my comments below:
On Mon, Jan 23, 2023 at 10:33 PM Andy Goryachev
wrote:
>
> Let me backtrack a bit and ask a very specific question: what is the problem
> (or problems) you are trying to solve?
> I would like to understand if the problem exists (more on that below), does a
> workaround exists or it is currently impossible to solve the problem using
> the existing APIs, and relative importance of the problem.
While JavaFX knows about themes (after all, it ships with two
hard-wired themes), it doesn't offer a public API for custom themes.
That's a bit of a problem, especially since the built-in themes look
quite dated.
Now, what's a theme? It's a dynamic collection of user-agent
stylesheets with a bit of logic determining when and how individual
stylesheets are included in the CSS cascade.
In the CSS subsystem, JavaFX already supports application-wide
user-agent stylesheet collections (that's how the built-in themes are
implemented).
The public API seems like an afterthought: you set
Application.userAgentStylesheet to some magic string to select a
built-theme.
But of course, developers want custom themes. There are two basic workarounds:
1) Add author stylesheets to the Scene
2) Replace the built-in theme with a single new user-agent stylesheet
The first option can be used to extend or modify the built-in theme,
but it does so by changing the semantics of the new styles: author
stylesheets override user code, while user-agent stylesheets don't.
The second option retains the semantics of themes (allow user code to
override properties), but comes at the price of being incredibly
clunky:
* You can only specify a single stylesheet, which means there's no way
to create a custom theme comprised of many individual stylesheets.
* You can't modify existing themes. Once you set a non-magic
Application.userAgentStylesheet, you lose all stylesheets that came
with the built-in themes.
* You can't even copy the built-in theme stylesheets and modify the
files to your liking, because that way you'll lose all of the dynamic
features (for example, reacting to the high contrast scheme setting).
If JavaFX is to stay relevant, it must give developers the tools they
need to create visually pleasing applications. Dynamic themes are
absolutely required for that (can you imagine a modern application
that doesn't support dark mode?).
> For example, when speaking about themes and missing APIs, I would say that
>
> 1. Large scale stylesheet change at run time (i.e. going from Modena to
> Caspian), or listing available stylesheets is probably not high on the list
> of desired features.
Going from Modena to Caspian and back is an existing feature, so
that's already there. What do you mean by "listing available
stylesheets", and how is it relevant to this PR?
> 2. What is high on the list of desired features is ability to select color
> theme (light/dark/hiContrast) at run time, possibly automatically by picking
> up the OS preference is it exists. Ideally, the color scheme would also pick
> up other, user-defined colors from the OS and integrate this into the current
> stylesheet (Modena). Right now there is no public API to support that, as
> far as I know, and no support in Modena.css
Since themes are an implementation detail right now, there's no public
API for anything of that sort.
The main premise of this PR is to promote themes to actual Java
classes. If you want to extend Modena, you simply extend the
javafx.scene.control.theme.ModenaTheme class and add your custom
stylesheets.
However, since modena.css is not designed to be extensible, the
ModenaTheme class also has very few extension points (basically just
an addFirst(String) and addLast(String) method to prepend or append
custom stylesheets).
If you wanted to make a version of Modena that supports dynamic
colors, you could do so by programmatically generating a small
stylesheet that only contains color definitions, and then simply swap
out this stylesheet in the ModenaTheme implementation whenever the
colors have changed. Of course, that also requires a bit of
refactoring of modena.css to remove the hard-coded colors. Note: it is
not a goal of this PR to refactor the built-in themes.
> 3. Another feature high on my wish list is ability to generate and apply CSS
> changes at run time. For example, reacting to the user selecting larger or
> smaller font, more spacious or compact style, and so on. Theoretically, this
> is possible by generating a new stylesheet (it has to be a heavily modified
> standard stylesheet) and feeding that to the Application using data: URL
> protocol.
Sure, that's theoretically possible. But it's probably not a good
developer story to dump the entirety of an application's theme
stylesheets into a single data URI.
With this PR, you could support a compact mode by creating a custom
theme and exposing an API for that:
public class MyCustomTheme implements StyleTheme {
private final
Re: [External] : Re: Style themes API
Michael:
Thank you for clarifications.
Let me backtrack a bit and ask a very specific question: what is the problem
(or problems) you are trying to solve?
I would like to understand if the problem exists (more on that below), does a
workaround exists or it is currently impossible to solve the problem using the
existing APIs, and relative importance of the problem.
For example, when speaking about themes and missing APIs, I would say that
1. Large scale stylesheet change at run time (i.e. going from Modena to
Caspian), or listing available stylesheets is probably not high on the list of
desired features.
2. What is high on the list of desired features is ability to select color
theme (light/dark/hiContrast) at run time, possibly automatically by picking up
the OS preference is it exists. Ideally, the color scheme would also pick up
other, user-defined colors from the OS and integrate this into the current
stylesheet (Modena). Right now there is no public API to support that, as far
as I know, and no support in Modena.css
3. Another feature high on my wish list is ability to generate and apply CSS
changes at run time. For example, reacting to the user selecting larger or
smaller font, more spacious or compact style, and so on. Theoretically, this
is possible by generating a new stylesheet (it has to be a heavily modified
standard stylesheet) and feeding that to the Application using data: URL
protocol.
4. Since you do mention javafx.application.Platform.Preferences in your PR, I
fully agree that it is a good idea to expose platform and preferences,
especially since there are no public APIs for that. This probably deserves its
own PR instead of being a part of #2. But the main value, as I see it (and I
could be wrong) is that the platform preferences are incorporated into the main
stylesheet.
Perhaps I totally misunderstand the goal of your PR #511, so could you please
describe the problem this PR is trying to solve?
Thank you
-andy
From: Michael Strauß
Date: Friday, 2023/01/13 at 16:14
To: Andy Goryachev
Cc: openjfx-dev
Subject: [External] : Re: Style themes API
Hi Andy!
please see my comments below:
On Fri, Jan 13, 2023 at 6:31 PM Andy Goryachev
wrote:
>
> #1 Theme
> I wonder if we need to clarify what we mean by the word "theme" in the
> context of a javaFX application. Are we talking about colors, fonts,
> spacing, graphics, or all of the above? Would a completely different
> stylesheet like Caspian or Modena be considered a separate theme, or would we
> rather have a way to modify the standard stylesheet by adding ability to
> redefine the different aspects such as colors and spacing without making
> structural changes to the stylesheet itself?
The proposed documentation defines it as: "StyleTheme is a collection
of stylesheets that specify the appearance of UI controls and other
nodes in the application."
So we're talking about everything that can be set via CSS. Caspian and
Modena are two separate themes, but they can be extended by prepending
or appending custom stylesheets.
One way to achieve this is by subclassing the
`javafx.scene.control.theme.CaspianTheme` or
`javafx.scene.control.theme.ModenaTheme` class and using the
`addFirst` and `addLast` methods to add custom stylesheets:
public class MyTheme extends ModenaTheme {
public MyTheme() {
addLast("myColors.css");
}
}
Note that `addFirst` and `addLast` are two methods that are specific
to the implementation of Caspian and Modena, these are not
general-purpose methods available for all `StyleTheme`
implementations.
Since both themes are implemented using a single CSS file, there is no
way to fundamentally change the structure of the theme.
However, other theme implementations may offer a different API that
may allow changing the stylesheets that comprise the theme in a
structural way.
For example, a theme implementation might use one stylesheet per
control instead of a single stylesheet for the entire theme, and offer
a way to override or modify individual control stylesheets.
> #2 Colors
> When talking about colors specifically, the main requirements might be:
> change the base colors used by the standard stylesheets, or just Modena
> derived colors might use different logic for light and dark themes
> have ability to select a group of colors, or "color themes" - such as Light,
> Dark, Solarized, High Contrast, etc.
> pick up the user-defined color preferences from the platform
> track the user-defined color preferences at run time
>
> I think most of these (except for platform colors) can be implemented
> currently at the application level (that is, without introducing new APIs)
> simply by loading a stylesheet that redefines base colors (e.g. -fx-base),
> however, it gets complicated when we start deriving colors. For example, the
>
Re: Style themes API
Hi Pedro,
see my comments below.
On Sat, Jan 21, 2023 at 5:19 PM Pedro Duque Vieira
wrote:
> I've been building javafx themes for years now. Started creating JMetro in
> JavaFX version 2. During this time I've been following how other themes are
> being built and I can say that about 90% of the themes (rough estimate) that
> are out there, are composed of author stylesheets, i.e they override values
> set from code (including JMetro).
> I agree that themes that are to be provided to other developers would
> probably be better off if they are user agent stylesheets. My point is that
> migrating those 90% of themes to use this API would be easier if this flag
> exists otherwise migration would likely introduce UI regressions for
> developers using those themes.
>
> To be clear, what I'm proposing is a flag, or enum, or whatever, in
> StyleTheme that defines whether the stylesheets in the StyleTheme should be a
> user agent stylesheet or author stylesheet.
>
> Another point is in making themes that are only to be used locally in a
> specific app that the developer is creating. It might be of interest that he
> can toggle this flag and make all settings defined in the theme override any
> styling set from code (or in FXML) so that he can have a centralized point
> where all styling is done.
I think that the likelihood of this feature making it into the 21
release dramatically increases if we keep changes to the CSS subsystem
to an absolute minimum. I understand your point, but I want to deliver
this feature in the smallest useful package and add more features
later with follow-on PRs.
That's why I've renamed `Application.styleTheme` to
`Application.userAgentStyleTheme`. This makes it unmistakably clear
that we're only talking about user-agent stylesheets.
Also, it leaves open the possibility to add the
`Application.styleTheme` property later, which would cause the theme
to be interpreted as comprised of author stylesheets.
Classifying author/UA themes at the property level is also more
consistent with the way author/UA stylesheets are currently classified
in JavaFX.
What do you think about the styleTheme/userAgentStyleTheme API,
instead of having a flag in the implementation of StyleTheme itself?
Since one of the objectives of the PR is to promote Caspian and Modena
to first-class theme implementations, it makes sense to focus on UA
themes first (since built-in themes are comprised of UA stylesheets).
> 3 -
> Style themes are generally either defined as dark or light. i.e. you'll very
> rarely have a theme that has some Windows with dark decorations and others
> with light decorations. So I think it makes sense to have this as a theme
> property.
> The ability to toggle decorations (light or dark) on an individual Window is
> a good point you're making. Perhaps we should have a global definition in the
> StyleTheme (whether the theme is light or dark) and a definition that can be
> set per Window.
> If you set it on the StyleTheme then all Windows will respect it, but you can
> override that value on each Window. If you override it on a specific Window,
> that definition would take precedence over the global StyleTheme one.
In general, StyleTheme is a very simple concept: it's a dynamic
collection of stylesheets.
I don't think the interface should force implementers to deal with
anything other than stylesheets. If we did that, the following code
wouldn't work any more:
Application.setUserAgentStyleTheme(
() -> List.of("stylesheet1.css", "stylesheet2.css");
Maybe we can add a new interface, for example DarkModeAware, and if an
application theme is marked with this interface, JavaFX will try to
respect dark/light mode for platform decorations:
public class MyCustomTheme implements StyleTheme, DarkModeAware {
@Override
public List getStylesheets() {
return List.of("stylesheet1.css", "stylesheet2.css");
}
}
// Setting a DarkModeAware theme causes JavaFX to draw light or
// dark platform decorations by default, depending on the current
// platform preference. If the theme is not DarkModeAware, JavaFX
// defaults to light decorations.
//
Application.setUserAgentStyleTheme(new MyCustomTheme());
In any case, I think we can deliver this feature in a follow-on PR.
> 4-
>>
>> If we wanted to expose this front-and-center, we could add these
>>
>> properties to the Platform.Properties interface:
>
>
>> public interface Preferences extends ObservableMap {
>> ReadOnlyBooleanProperty darkModeProperty();
>> ReadOnlyObjectProperty accentColorProperty();
>> ...
>> }
>
>
> Yes, I think that would be great.
Let's see what other people think.
Re: Style themes API
Hi again Michael,
2-
> Currently, the order of precedence is as follows (from highest to lowest):
> 1. Node.style
> 2. Parent.stylesheets
> 3. Scene.stylesheets
> 4. StyleableProperty values set from code
> 5. Application.styleTheme
> 6. Application.userAgentStylesheet
I understand you're suggesting that a style theme could effectively be
> inserted between 3 and 4, such that it overrides local values set from
> code, but not values set in Scene stylesheets.
> I'm not sure that the added complexity is worth the marginal benefits.
> As far as JavaFX has always had the concept of built-in "themes",
> users could reliably override any StyleableProperty value from code.
> Developers might be surprised to find out that they can't set the
> value of a StyleableProperty from code because an application-wide
> style theme overrides any local changes.
> The migration story from Scene stylesheets to a StyleTheme might be a
> little bit easier, but it complicates the mental model of how themes
> interact with the CSS cascade.
I've been building javafx themes for years now. Started creating JMetro in
JavaFX version 2. During this time I've been following how other themes are
being built and I can say that about 90% of the themes (rough estimate)
that are out there, are composed of author stylesheets, i.e they override
values set from code (including JMetro).
I agree that themes that are to be provided to other developers would
probably be better off if they are user agent stylesheets. My point is that
migrating those 90% of themes to use this API would be easier if this flag
exists otherwise migration would likely introduce UI regressions for
developers using those themes.
To be clear, what I'm proposing is a flag, or enum, or whatever, in
StyleTheme that defines whether the stylesheets in the StyleTheme should be
a user agent stylesheet or author stylesheet.
Another point is in making themes that are only to be used locally in a
specific app that the developer is creating. It might be of interest that
he can toggle this flag and make all settings defined in the theme override
any styling set from code (or in FXML) so that he can have a centralized
point where all styling is done.
3 -
> I agree that it would be nice to have a way to programmatically
> control the appearance of system-provided window decorations.
> It's not entirely related to style themes: a style theme is an
> application-wide concept, while window decorations are specific to
> each individual window.
> Maybe we could do this similarly to the Stage.initStyle method, which
> serves a similar purpose of setting up window decorations.
Style themes are generally either defined as dark or light. i.e. you'll
very rarely have a theme that has some Windows with dark decorations and
others with light decorations. So I think it makes sense to have this as a
theme property.
The ability to toggle decorations (light or dark) on an individual Window
is a good point you're making. Perhaps we should have a global definition
in the StyleTheme (whether the theme is light or dark) and a definition
that can be set per Window.
If you set it on the StyleTheme then all Windows will respect it, but you
can override that value on each Window. If you override it on a specific
Window, that definition would take precedence over the global StyleTheme
one.
4-
> If we wanted to expose this front-and-center, we could add these
properties to the Platform.Properties interface:
public interface Preferences extends ObservableMap {
> ReadOnlyBooleanProperty darkModeProperty();
> ReadOnlyObjectProperty accentColorProperty();
> ...
> }
Yes, I think that would be great.
Thanks again!
On Mon, Jan 16, 2023 at 11:28 PM Michael Strauß
wrote:
> Hi Pedro,
> see my comments below.
>
>
> On Mon, Jan 16, 2023 at 1:10 PM Pedro Duque Vieira
> wrote:
> >
> > No problem, I mentioned those in my first comment but probably got lost
> in this conversation.
> > 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'll now also add that you might want to create a theme, from the get
> go, that doesn't get trumped by any rule set through code, either code
> itself on in FXML files (which will be code anyway). So that the theme css
> is what always drives the presentation of your app (it has priority).
> > This is already possible by choosing to add your stylesheets to the
> Scene getStylesheets() method or by using the setUserAgentStylesheet()
> method.
>
>
Re: Style themes API
Hi Pedro,
see my comments below.
On Mon, Jan 16, 2023 at 1:10 PM Pedro Duque Vieira
wrote:
>
> No problem, I mentioned those in my first comment but probably got lost in
> this conversation.
> 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'll now also add that you might want to create a theme, from the get go,
> that doesn't get trumped by any rule set through code, either code itself on
> in FXML files (which will be code anyway). So that the theme css is what
> always drives the presentation of your app (it has priority).
> This is already possible by choosing to add your stylesheets to the Scene
> getStylesheets() method or by using the setUserAgentStylesheet() method.
Currently, the order of precedence is as follows (from highest to lowest):
1. Node.style
2. Parent.stylesheets
3. Scene.stylesheets
4. StyleableProperty values set from code
5. Application.styleTheme
6. Application.userAgentStylesheet
I understand you're suggesting that a style theme could effectively be
inserted between 3 and 4, such that it overrides local values set from
code, but not values set in Scene stylesheets.
I'm not sure that the added complexity is worth the marginal benefits.
As far as JavaFX has always had the concept of built-in "themes",
users could reliably override any StyleableProperty value from code.
Developers might be surprised to find out that they can't set the
value of a StyleableProperty from code because an application-wide
style theme overrides any local changes.
The migration story from Scene stylesheets to a StyleTheme might be a
little bit easier, but it complicates the mental model of how themes
interact with the CSS cascade.
> Ok thanks for clarifying what happens on Mac. Yes on the Windows OS, JavaFX
> won't honor your system wide settings. If your system is in dark mode the
> frames will still be shown in light mode.
> But anyways, I think, the programmer should be able to toggle the dark/light
> mode setting irrespective of what is defined in the system. There are many
> apps where you, as a user, can choose dark or light mode in the app itself
> and it will honor it regardless of what you have defined in the system (e.g.
> Intellij, Slack, etc, etc). Some will allow you to set whether you want to
> use the system setting for light/dark mode or your own setting in the app.
> This can be of value in cases where you, as a user, prefer to use an app in
> dark mode and others in some other mode, so you can choose themes on an app
> by app basis.
> Or perhaps the developer wants to design an app that's just dark. In that
> case you'd want the ability to toggle the frame decorations to being dark
> (all the time).
I agree that it would be nice to have a way to programmatically
control the appearance of system-provided window decorations.
It's not entirely related to style themes: a style theme is an
application-wide concept, while window decorations are specific to
each individual window.
Maybe we could do this similarly to the Stage.initStyle method, which
serves a similar purpose of setting up window decorations.
> Just to be clear I was just talking about how we would present this API
> (platform preferences). This property would be a way to more easily know if
> the system is in dark/light mode, the accent color, without needing to know
> the specific "key".
If we wanted to expose this front-and-center, we could add these
properties to the Platform.Properties interface:
public interface Preferences extends ObservableMap {
ReadOnlyBooleanProperty darkModeProperty();
ReadOnlyObjectProperty accentColorProperty();
...
}
Re: Style themes API
Hi again Michael, Thanks for taking the time to answer my comments. As always, it's easier to comment on and criticize than to do the actual work of implementing the feature. So thanks again for the patience. My comments below: I don't quite understand this. Can you elaborate on what the > advantages would be, and how (and for what purpose) users of the API > would use such a flag? No problem, I mentioned those in my first comment but probably got lost in this conversation. 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'll now also add that you might want to create a theme, from the get go, that doesn't get trumped by any rule set through code, either code itself on in FXML files (which will be code anyway). So that the theme css is what always drives the presentation of your app (it has priority). This is already possible by choosing to add your stylesheets to the Scene getStylesheets() method or by using the setUserAgentStylesheet() method. I don't think that we need any new API for dark mode window frames. > On macOS, the color of the window frame is already adjusted to match > the system-wide dark/light mode. > On Windows, this is not the case: https://learn.microsoft.com/en-us/windows/apps/desktop/modernize/apply-windows-themes "Not all Win32 applications support Dark mode, so > Windows gives Win32 apps a light title bar by > default. If you are prepared to support Dark mode, > you can ask Windows to draw the dark title bar > instead when Dark mode is enabled." Since JavaFX already uses dark frames on macOS, why not do the same on > Windows? > We can simply enable this behavior in general, and provide a system > property to revert to the old behavior of always using light frames, > even if dark mode is enabled. Ok thanks for clarifying what happens on Mac. Yes on the Windows OS, JavaFX won't honor your system wide settings. If your system is in dark mode the frames will still be shown in light mode. But anyways, I think, the programmer should be able to toggle the dark/light mode setting irrespective of what is defined in the system. There are many apps where you, as a user, can choose dark or light mode in the app itself and it will honor it regardless of what you have defined in the system (e.g. Intellij, Slack, etc, etc). Some will allow you to set whether you want to use the system setting for light/dark mode or your own setting in the app. This can be of value in cases where you, as a user, prefer to use an app in dark mode and others in some other mode, so you can choose themes on an app by app basis. Or perhaps the developer wants to design an app that's just dark. In that case you'd want the ability to toggle the frame decorations to being dark (all the time). Here's a simple implementation that exposes dark mode and accent > coloring as JavaFX properties on a theme base class: > https://gist.github.com/mstr2/ba2f9cba659953788008fed1e9b2a031 We might consider adding something like this to JavaFX in the future, > but for the time being, I'd rather let third-party libraries explore > higher-level APIs first. Just to be clear I was just talking about how we would present this API (platform preferences). This property would be a way to more easily know if the system is in dark/light mode, the accent color, without needing to know the specific "key". Thanks again! On Mon, Jan 16, 2023 at 4:01 AM Michael Strauß wrote: > My comments below: > > On Sun, Jan 15, 2023 at 1:25 PM Pedro Duque Vieira > wrote: > > > > I think we could add that it has higher precedence than a user agent > stylesheets but that's it's not an author stylesheet. We can also possibly > briefly say what a user agent stylesheet and author stylesheet are or > perhaps better yet, point to the css reference doc section that states it? > > Sure, I'll add some additional documentation. > > > > > Yes, I think minimizing changes to the CSS subsystem is a good idea. > > I didn't mean we should make changes to the CSS subsystem, I > meant/proposed to add a flag or property in StyleThemes (the new API) that > programmers would then set in their StyleThemes and would define whether > the StyleTheme he's creating is a user agent stylesheet or an author > stylesheet. > > I don't quite understand this. Can you elaborate on what the > advantages would be, and how (and for what purpose) users of the API > would use such a flag? > > > > > I disagree here. I think this would be too low level for third party > apps to add
Re: Style themes API
My comments below: On Sun, Jan 15, 2023 at 1:25 PM Pedro Duque Vieira wrote: > > I think we could add that it has higher precedence than a user agent > stylesheets but that's it's not an author stylesheet. We can also possibly > briefly say what a user agent stylesheet and author stylesheet are or perhaps > better yet, point to the css reference doc section that states it? Sure, I'll add some additional documentation. > Yes, I think minimizing changes to the CSS subsystem is a good idea. > I didn't mean we should make changes to the CSS subsystem, I meant/proposed > to add a flag or property in StyleThemes (the new API) that programmers would > then set in their StyleThemes and would define whether the StyleTheme he's > creating is a user agent stylesheet or an author stylesheet. I don't quite understand this. Can you elaborate on what the advantages would be, and how (and for what purpose) users of the API would use such a flag? > I disagree here. I think this would be too low level for third party apps to > add support for, and as of today there isn't still yet any third party > library that adds it (which can itself be an indication that it's not a good > fit for third party libraries). > You'd need third party libraries to call on native code to change the frame > decoration of Windows that JavaFX spawns itself. > This API will already add some nice support to query platform preferences > (dark mode, accent color, etc) so I think it makes perfect sense to also add > API here to set the programmers preferences about these properties, that > JavaFX should then abide by. > > Yes we could come back later to add that API. > As a theme developer and focusing on theme development only, this has been on > top of my wish list for a while. :) > Given that light/dark theme, etc feature is pervasive across all Oses I think > it's a shame that JavaFX doesn't yet fully support the development of > light/dark themes (especially dark themes). I don't think that we need any new API for dark mode window frames. On macOS, the color of the window frame is already adjusted to match the system-wide dark/light mode. On Windows, this is not the case: https://learn.microsoft.com/en-us/windows/apps/desktop/modernize/apply-windows-themes "Not all Win32 applications support Dark mode, so Windows gives Win32 apps a light title bar by default. If you are prepared to support Dark mode, you can ask Windows to draw the dark title bar instead when Dark mode is enabled." Since JavaFX already uses dark frames on macOS, why not do the same on Windows? We can simply enable this behavior in general, and provide a system property to revert to the old behavior of always using light frames, even if dark mode is enabled. > 4 - After reading Andy's comments I thought about a 4th point. > I agree with him in the part that we could have some of the platform > preference properties as Java properties. At least the things that are > pervasive across platforms, like whether the platform is set to dark or light > mode and the accent color. > I mean this in addition to the API that queries for platform properties (i.e. > I don't mean to remove the API you proposed to query for platform properties). Here's a simple implementation that exposes dark mode and accent coloring as JavaFX properties on a theme base class: https://gist.github.com/mstr2/ba2f9cba659953788008fed1e9b2a031 We might consider adding something like this to JavaFX in the future, but for the time being, I'd rather let third-party libraries explore higher-level APIs first.
Re: Style themes API
Hi Michael, Thanks again for taking the time to answer my questions/comments and for your efforts in coming forward with this new API proposal. And also thanks for your patience as I can be a bit annoying at times. :) There's of course a bunch of things I liked about your API proposal but for the sake of time I specifically only commented on what I thought could change and not on what I liked (I don't have much free spare time at the moment, unfortunately). There's of course your idea itself of adding a Theme API which I agree with. Answering your comments below: 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. I think we could add that it has higher precedence than a user agent stylesheets but that's it's not an author stylesheet. We can also possibly briefly say what a user agent stylesheet and author stylesheet are or perhaps better yet, point to the css reference doc section that states it? 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. Yes, I think minimizing changes to the CSS subsystem is a good idea. I didn't mean we should make changes to the CSS subsystem, I meant/proposed to add a flag or property in StyleThemes (the new API) that programmers would then set in their StyleThemes and would define whether the StyleTheme he's creating is a user agent stylesheet or an author stylesheet. 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. I disagree here. I think this would be too low level for third party apps to add support for, and as of today there isn't still yet any third party library that adds it (which can itself be an indication that it's not a good fit for third party libraries). You'd need third party libraries to call on native code to change the frame decoration of Windows that JavaFX spawns itself. This API will already add some nice support to query platform preferences (dark mode, accent color, etc) so I think it makes perfect sense to also add API here to set the programmers preferences about these properties, that JavaFX should then abide by. Yes we could come back later to add that API. As a theme developer and focusing on theme development only, this has been on top of my wish list for a while. :) Given that light/dark theme, etc feature is pervasive across all Oses I think it's a shame that JavaFX doesn't yet fully support the development of light/dark themes (especially dark themes). 4 - After reading Andy's comments I thought about a 4th point. I agree with him in the part that we could have some of the platform preference properties as Java properties. At least the things that are pervasive across platforms, like whether the platform is set to dark or light mode and the accent color. I mean this in addition to the API that queries for platform properties (i.e. I don't mean to remove the API you proposed to query for platform properties). Thanks again! -- Pedro Duque Vieira - https://www.pixelduke.com
Re: Style themes API
Hi Pedro, please see my comments below: On Fri, Jan 13, 2023 at 10:06 PM Pedro Duque Vieira 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.
Re: Style themes API
Hi Andy!
please see my comments below:
On Fri, Jan 13, 2023 at 6:31 PM Andy Goryachev
wrote:
>
> #1 Theme
> I wonder if we need to clarify what we mean by the word "theme" in the
> context of a javaFX application. Are we talking about colors, fonts,
> spacing, graphics, or all of the above? Would a completely different
> stylesheet like Caspian or Modena be considered a separate theme, or would we
> rather have a way to modify the standard stylesheet by adding ability to
> redefine the different aspects such as colors and spacing without making
> structural changes to the stylesheet itself?
The proposed documentation defines it as: "StyleTheme is a collection
of stylesheets that specify the appearance of UI controls and other
nodes in the application."
So we're talking about everything that can be set via CSS. Caspian and
Modena are two separate themes, but they can be extended by prepending
or appending custom stylesheets.
One way to achieve this is by subclassing the
`javafx.scene.control.theme.CaspianTheme` or
`javafx.scene.control.theme.ModenaTheme` class and using the
`addFirst` and `addLast` methods to add custom stylesheets:
public class MyTheme extends ModenaTheme {
public MyTheme() {
addLast("myColors.css");
}
}
Note that `addFirst` and `addLast` are two methods that are specific
to the implementation of Caspian and Modena, these are not
general-purpose methods available for all `StyleTheme`
implementations.
Since both themes are implemented using a single CSS file, there is no
way to fundamentally change the structure of the theme.
However, other theme implementations may offer a different API that
may allow changing the stylesheets that comprise the theme in a
structural way.
For example, a theme implementation might use one stylesheet per
control instead of a single stylesheet for the entire theme, and offer
a way to override or modify individual control stylesheets.
> #2 Colors
> When talking about colors specifically, the main requirements might be:
> change the base colors used by the standard stylesheets, or just Modena
> derived colors might use different logic for light and dark themes
> have ability to select a group of colors, or "color themes" - such as Light,
> Dark, Solarized, High Contrast, etc.
> pick up the user-defined color preferences from the platform
> track the user-defined color preferences at run time
>
> I think most of these (except for platform colors) can be implemented
> currently at the application level (that is, without introducing new APIs)
> simply by loading a stylesheet that redefines base colors (e.g. -fx-base),
> however, it gets complicated when we start deriving colors. For example, the
> use of derive() will need to change in order to obtain an esthetically
> pleasing colors in the dark theme.
All of these things (except as you say, querying and tracking changes
of platform colors) can be currently implemented by programmatically
composing a monolithic user-agent stylesheet. The advantage of this
approach is that you can use any kind of logic, not just what's
supported by JavaFX CSS functions like derive().
> #3 Platform Colors
> Thank you for researching the preferences provided by the three different
> platforms. I wonder if it would make sense to extract that into a separate
> PR, perhaps as an implementation detail, to be further refined as a part of
> Desktop replacement for JavaFX? And, if we are talking about exposing
> platform colors via APIs, do we want to make it as a part of one giant
> facility like java.swt.Desktop equivalent, or via individual methods in
> Platform, or perhaps some other lookup scheme that allows for future
> extension?
> Do you think it could be possible to describe the individual platform
> properties (what is Windows.UIColor.AccentDark3?), and possibly attempt to
> map platform-specific properties to a platform-independent set of properties
> which represent a union of the three major platforms?
> There is one more complication - constant changes in the platform design
> language. Ideally, any new APIs would support gradual evolution of the
> platform by, for example, providing methods to query whether particular item
> is available or not.
The platform preferences API is an integral part of the value
proposition of style themes. JavaFX has long included a very limited
form of this (not as public API), built specifically to support
Windows high contrast themes.
I don't think that it makes sense to separate the platform preferences
API from style themes, because
a) the existing support for Windows high contrast themes must continue
to work with the new first-class theme implementations, which requires
new code that will instantly be rendered irrelevant when the platform
preferences API arrives. Not a good investment of our time.
b) leveraging the platform preferences API to support platform
dark/light modes will probably be the first
Re: Style themes API
Dear Michael: Thank you for initiating this discussion and providing a pull request! I would like to make a few comments and ask your opinion on some of the difficulties the application developers face when confronted with requirements to provide a custom styling or even a completely different look and feel. I'll try to number the individual topics, but please forgive me if this message turns out to be long and jumbled. #1 Theme I wonder if we need to clarify what we mean by the word "theme" in the context of a javaFX application. Are we talking about colors, fonts, spacing, graphics, or all of the above? Would a completely different stylesheet like Caspian or Modena be considered a separate theme, or would we rather have a way to modify the standard stylesheet by adding ability to redefine the different aspects such as colors and spacing without making structural changes to the stylesheet itself? #2 Colors When talking about colors specifically, the main requirements might be: * change the base colors used by the standard stylesheets, or just Modena * derived colors might use different logic for light and dark themes * have ability to select a group of colors, or "color themes" - such as Light, Dark, Solarized, High Contrast, etc. * pick up the user-defined color preferences from the platform * track the user-defined color preferences at run time I think most of these (except for platform colors) can be implemented currently at the application level (that is, without introducing new APIs) simply by loading a stylesheet that redefines base colors (e.g. -fx-base), however, it gets complicated when we start deriving colors. For example, the use of derive() will need to change in order to obtain an esthetically pleasing colors in the dark theme. #3 Platform Colors Thank you for researching the preferences provided by the three different platforms. I wonder if it would make sense to extract that into a separate PR, perhaps as an implementation detail, to be further refined as a part of Desktop replacement for JavaFX? And, if we are talking about exposing platform colors via APIs, do we want to make it as a part of one giant facility like java.swt.Desktop equivalent, or via individual methods in Platform, or perhaps some other lookup scheme that allows for future extension? Do you think it could be possible to describe the individual platform properties (what is Windows.UIColor.AccentDark3?), and possibly attempt to map platform-specific properties to a platform-independent set of properties which represent a union of the three major platforms? There is one more complication - constant changes in the platform design language. Ideally, any new APIs would support gradual evolution of the platform by, for example, providing methods to query whether particular item is available or not. #4 Spacing and Font Size A lot of modern UIs introduced the concept of density (for example, in MS Outlook, Preferences -> General -> Density preference), by making spacing between UI elements larger or smaller (at run time). Similarly, the font size can be made larger or smaller (Ctrl-+ / Ctrl-- in Firefox). The font size change affects "em" units, perhaps we need a parallel construct like "space-em" units that is applied to spacing? Even then, we might need special logic to switch from pixels to fractions of "space-em" for large scales. How can we enable this functionality, ideally without making drastic changes to the base stylesheet? Is it even possible? #5 Programmatic Stylesheet Generation Somewhere in this discussion we might also consider adding a possibility of generating a stylesheet programmatically, ideally in a type-safe manner, compatible with auto-completion. jfx17 (I think) added a way to load a stylesheet data url, so it is much easier now, but I think a better way would be to skip the encoding/decoding step and just generate the stylesheet object directly. Perhaps the ideal scenario, one that makes it possible to adjust every aspect of the application styling, is to generate the complete stylesheet at run time, and possibly passing it to JavaFx in a binary form that does not require parsing. I understand this is totally separate issue which will no doubt require its own discussion. What do you think? -andy From: openjfx-dev on behalf of Michael Strauß Date: Saturday, 2023/01/07 at 10:35 To: openjfx-dev Subject: Style themes API The following PR introduces new APIs to support style themes in JavaFX: https://github.com/openjdk/jfx/pull/511 As Kevin already indicated, we need to finish the discussion on the proposed API. I'd like to invite comments or suggestions with regards to the API to hopefully get a bit of momentum for this feature to make it into the 21 release. Michael
Style themes API
The following PR introduces new APIs to support style themes in JavaFX: https://github.com/openjdk/jfx/pull/511 As Kevin already indicated, we need to finish the discussion on the proposed API. I'd like to invite comments or suggestions with regards to the API to hopefully get a bit of momentum for this feature to make it into the 21 release. Michael
