Re: RFR: 8267546: Add CSS themes as a first-class concept [v18]
On Mon, 9 Jan 2023 18:33:40 GMT, Michael Strauß wrote:
>> This PR adds style themes as a first-class concept to OpenJFX. A style theme
>> is a collection of stylesheets and the logic that governs them. Style themes
>> can respond to OS notifications and update their stylesheets dynamically.
>> This PR also re-implements Caspian and Modena as style themes.
>>
>> ### New APIs in `javafx.graphics`
>> The new theming-related APIs in `javafx.graphics` provide a basic framework
>> to support application-wide style themes. Higher-level theming concepts (for
>> example, "dark mode" detection or accent coloring) are not a part of this
>> basic framework, because any API invented here might soon be out of date.
>> Implementations can build on top of this framework to add useful
>> higher-level features.
>> 1. StyleTheme
>> A style theme is an implementation of the `javafx.css.StyleTheme` interface:
>>
>> /**
>> * {@code StyleTheme} is a collection of stylesheets that specify the
>> appearance of UI controls and other
>> * nodes in the application. Like a user-agent stylesheet, a {@code
>> StyleTheme} is implicitly used by all
>> * JavaFX nodes in the scene graph.
>> *
>> * The list of stylesheets that comprise a {@code StyleTheme} can be
>> modified while the application is running,
>> * enabling applications to create dynamic themes that respond to changing
>> user preferences.
>> *
>> * In the CSS subsystem, stylesheets that comprise a {@code StyleTheme} are
>> classified as
>> * {@link StyleOrigin#USER_AGENT} stylesheets, but have a higher precedence
>> in the CSS cascade
>> * than a stylesheet referenced by {@link
>> Application#userAgentStylesheetProperty()}.
>> */
>> public interface StyleTheme {
>> /**
>> * Gets the list of stylesheet URLs that comprise this {@code
>> StyleTheme}.
>> *
>> * If the list of stylesheets that comprise this {@code StyleTheme} is
>> changed at runtime, this
>> * method must return an {@link ObservableList} to allow the CSS
>> subsystem to subscribe to list
>> * change notifications.
>> *
>> * @implSpec Implementations of this method that return an {@link
>> ObservableList} must emit all
>> * change notifications on the JavaFX application thread.
>> *
>> * @implNote Implementations of this method that return an {@link
>> ObservableList} are encouraged
>> * to minimize the number of subsequent list change
>> notifications that are fired by the
>> * list, as each change notification causes the CSS subsystem
>> to re-apply the referenced
>> * stylesheets.
>> */
>> List getStylesheets();
>> }
>>
>>
>> A new `styleTheme` property is added to `javafx.application.Application`,
>> and `userAgentStylesheet` is promoted to a JavaFX property (currently, this
>> is just a getter/setter pair):
>>
>> public class Application {
>> ...
>> /**
>> * Specifies the user-agent stylesheet of the application.
>> *
>> * A user-agent stylesheet is a global stylesheet that can be specified
>> in addition to a
>> * {@link StyleTheme} and that is implicitly used by all JavaFX nodes in
>> the scene graph.
>> * It can be used to provide default styling for UI controls and other
>> nodes.
>> * A user-agent stylesheets has the lowest precedence in the CSS cascade.
>> *
>> * Before JavaFX 21, built-in themes were selectable using the special
>> user-agent stylesheet constants
>> * {@link #STYLESHEET_CASPIAN} and {@link #STYLESHEET_MODENA}. For
>> backwards compatibility, the meaning
>> * of these special constants is retained: setting the user-agent
>> stylesheet to either {@code STYLESHEET_CASPIAN}
>> * or {@code STYLESHEET_MODENA} will also set the value of the {@link
>> #styleThemeProperty() styleTheme}
>> * property to a new instance of the corresponding theme class.
>> *
>> * Note: this property can be modified on any thread, but it is not
>> thread-safe and must
>> * not be concurrently modified with {@link #styleThemeProperty()
>> styleTheme}.
>> */
>> public static StringProperty userAgentStylesheetProperty();
>> public static String getUserAgentStylesheet();
>> public static void setUserAgentStylesheet(String url);
>>
>> /**
>> * Specifies the {@link StyleTheme} of the application.
>> *
>> * {@code StyleTheme} is a collection of stylesheets that define the
>> appearance of the application.
>> * Like a user-agent stylesheet, a {@code StyleTheme} is implicitly used
>> by all JavaFX nodes in the
>> * scene graph.
>> *
>> * Stylesheets that comprise a {@code StyleTheme} have a higher
>> precedence in the CSS cascade than a
>> * stylesheet referenced by the {@link #userAgentStylesheetProperty()
>> userAgentStylesheet} property.
>> *
>> * Note: this property can be
Re: RFR: 8267546: Add CSS themes as a first-class concept [v18]
> This PR adds style themes as a first-class concept to OpenJFX. A style theme
> is a collection of stylesheets and the logic that governs them. Style themes
> can respond to OS notifications and update their stylesheets dynamically.
> This PR also re-implements Caspian and Modena as style themes.
>
> ### New APIs in `javafx.graphics`
> The new theming-related APIs in `javafx.graphics` provide a basic framework
> to support application-wide style themes. Higher-level theming concepts (for
> example, "dark mode" detection or accent coloring) are not a part of this
> basic framework, because any API invented here might soon be out of date.
> Implementations can build on top of this framework to add useful higher-level
> features.
> 1. StyleTheme
> A style theme is an implementation of the `javafx.css.StyleTheme` interface:
>
> /**
> * {@code StyleTheme} is a collection of stylesheets that specify the
> appearance of UI controls and other
> * nodes in the application. Like a user-agent stylesheet, a {@code
> StyleTheme} is implicitly used by all
> * JavaFX nodes in the scene graph.
> *
> * The list of stylesheets that comprise a {@code StyleTheme} can be modified
> while the application is running,
> * enabling applications to create dynamic themes that respond to changing
> user preferences.
> *
> * In the CSS subsystem, stylesheets that comprise a {@code StyleTheme} are
> classified as
> * {@link StyleOrigin#USER_AGENT} stylesheets, but have a higher precedence
> in the CSS cascade
> * than a stylesheet referenced by {@link
> Application#userAgentStylesheetProperty()}.
> */
> public interface StyleTheme {
> /**
> * Gets the list of stylesheet URLs that comprise this {@code StyleTheme}.
> *
> * If the list of stylesheets that comprise this {@code StyleTheme} is
> changed at runtime, this
> * method must return an {@link ObservableList} to allow the CSS
> subsystem to subscribe to list
> * change notifications.
> *
> * @implSpec Implementations of this method that return an {@link
> ObservableList} must emit all
> * change notifications on the JavaFX application thread.
> *
> * @implNote Implementations of this method that return an {@link
> ObservableList} are encouraged
> * to minimize the number of subsequent list change
> notifications that are fired by the
> * list, as each change notification causes the CSS subsystem
> to re-apply the referenced
> * stylesheets.
> */
> List getStylesheets();
> }
>
>
> A new `styleTheme` property is added to `javafx.application.Application`, and
> `userAgentStylesheet` is promoted to a JavaFX property (currently, this is
> just a getter/setter pair):
>
> public class Application {
> ...
> /**
> * Specifies the user-agent stylesheet of the application.
> *
> * A user-agent stylesheet is a global stylesheet that can be specified
> in addition to a
> * {@link StyleTheme} and that is implicitly used by all JavaFX nodes in
> the scene graph.
> * It can be used to provide default styling for UI controls and other
> nodes.
> * A user-agent stylesheets has the lowest precedence in the CSS cascade.
> *
> * Before JavaFX 21, built-in themes were selectable using the special
> user-agent stylesheet constants
> * {@link #STYLESHEET_CASPIAN} and {@link #STYLESHEET_MODENA}. For
> backwards compatibility, the meaning
> * of these special constants is retained: setting the user-agent
> stylesheet to either {@code STYLESHEET_CASPIAN}
> * or {@code STYLESHEET_MODENA} will also set the value of the {@link
> #styleThemeProperty() styleTheme}
> * property to a new instance of the corresponding theme class.
> *
> * Note: this property can be modified on any thread, but it is not
> thread-safe and must
> * not be concurrently modified with {@link #styleThemeProperty()
> styleTheme}.
> */
> public static StringProperty userAgentStylesheetProperty();
> public static String getUserAgentStylesheet();
> public static void setUserAgentStylesheet(String url);
>
> /**
> * Specifies the {@link StyleTheme} of the application.
> *
> * {@code StyleTheme} is a collection of stylesheets that define the
> appearance of the application.
> * Like a user-agent stylesheet, a {@code StyleTheme} is implicitly used
> by all JavaFX nodes in the
> * scene graph.
> *
> * Stylesheets that comprise a {@code StyleTheme} have a higher
> precedence in the CSS cascade than a
> * stylesheet referenced by the {@link #userAgentStylesheetProperty()
> userAgentStylesheet} property.
> *
> * Note: this property can be modified on any thread, but it is not
> thread-safe and must not be
> * concurrently modified with {@link #userAgentStylesheetProperty()
> userAgentStylesheet}.
>
