Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8267540

Add themes as a first-class concept

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Withdrawn
    • Fix Version/s: None
    • Component/s: javafx
    • Labels:
      None
    • Subcomponent:
    • Compatibility Risk:
      medium
    • Compatibility Risk Description:
      This change can potentially break existing themes, particularly for uncommon and less often tested platforms.
    • Scope:
      JDK

      Description

      Summary

      Introduce javafx.application.Theme to implement themes as collections of stylesheets and the logic that governs their behavior.

      Problem

      Currently, the two themes shipped with JavaFX (Caspian and Modena) are implemented as a set of stylesheets and some internal logic, mostly in PlatformImpl.

      Much of this logic deals with optional features or platform-specific theme modifications. Another piece of logic deals with accessibility themes: on Windows platforms, both Caspian and Modena have high-contrast stylesheets that are added or removed in response to OS theme changes.

      A major downside of this implementation is that it special-cases the built-in themes and doesn't offer enough extension points to make it easy for developers to create new rich themes.

      Solution

      This PR adds a new interface in the javafx.application package:

      public interface Theme {
          ObservableList<String> getStylesheets();
          void platformThemeChanged(Map<String, String> properties);
      }

      An implementation of this interface populates the list returned by Theme.getStylesheets() with its collection of stylesheets. Optionally, it can listen to the platform theme properties reported by Theme.platformThemeChanged(...) and modify its list of stylesheets accordingly.

      Platform theme properties are platform-specific key-value pairs, and theme implementations are responsible for interpreting the values. For example, on the Windows platform, a theme implementation might listen to the Windows.SPI_HighContrastOn property in order to detect whether or not a high-contrast stylesheet should be used. The Theme class documents all currently supported platform properties.

      A theme is activated by setting it as the user-agent stylesheet of the application:

      Application.setUserAgentStylesheet("theme:com.example.CustomTheme");

      "theme:" is a custom URI scheme that is interpreted when the user-agent stylesheet is loaded.

      The existing constants Application.STYLESHEET_CASPIAN and Application.STYLESHEET_MODENA are redefined to their new Theme implementations.

      Specification

      Add a new javafx.application.Theme interface:

      /**
       * A theme is a set of stylesheets that define the visual
       * appearance of an application.
       * <p>
       * Themes can be static (i.e. the set of stylesheets is defined
       * by the theme creator and never changes), or they can respond
       * to the platform theme exposed by the operating system.
       * Platform theme properties are key-value pairs that describe
       * the underlying platform theme. Different operating systems
       * will often have a different set of platform theme properties.
       * For example, Windows 10 has accent colors that are not
       * available in earlier versions of Windows.
       * <p>
       * A theme implementation must have either
       * <ol>
       *     <li>a parameterless constructor, or
       *     <li>a single-argument constructor that accepts a
       *         {@link Map Map&lt;String, String&gt;}, which is the
       *         set of theme properties reported by the platform.
       * </ol>
       * Themes are instantiated by the JavaFX theming system.
       * In order to load a custom theme, call
       * {@link Application#setUserAgentStylesheet(String)}
       * with a theme-URI that contains the name of the theme class:
       * <pre><code>
       *     Application.setUserAgentStylesheet("theme:com.example.CustomTheme");
       * </code></pre>
       * It is the responsibility of the theme creator to interpret
       * platform theme properties.
       * <p>
       * Currently, only Windows platforms report theme properties:
       * <ol>
       *     <li>High contrast color scheme (as reported by SystemParametersInfo):
       *     <ul>
       *         <li>Windows.SPI_HighContrastOn: "true" | "false"
       *         <li>Windows.SPI_HighContrastColorScheme: string
       *     </ul>
       *     <li>System colors (as reported by GetSysColor): hex-color-string
       *     <ul>
       *         <li>Windows.SysColor.COLOR_3DDKSHADOW: hex-color-string
       *         <li>Windows.SysColor.COLOR_3DFACE: hex-color-string
       *         <li>Windows.SysColor.COLOR_3DHIGHLIGHT: hex-color-string
       *         <li>Windows.SysColor.COLOR_3DHILIGHT: hex-color-string
       *         <li>Windows.SysColor.COLOR_3DLIGHT: hex-color-string
       *         <li>Windows.SysColor.COLOR_3DSHADOW: hex-color-string
       *         <li>Windows.SysColor.COLOR_ACTIVEBORDER: hex-color-string
       *         <li>Windows.SysColor.COLOR_ACTIVECAPTION: hex-color-string
       *         <li>Windows.SysColor.COLOR_APPWORKSPACE: hex-color-string
       *         <li>Windows.SysColor.COLOR_BACKGROUND: hex-color-string
       *         <li>Windows.SysColor.COLOR_BTNFACE: hex-color-string
       *         <li>Windows.SysColor.COLOR_BTNHIGHLIGHT: hex-color-string
       *         <li>Windows.SysColor.COLOR_BTNHILIGHT: hex-color-string
       *         <li>Windows.SysColor.COLOR_BTNSHADOW: hex-color-string
       *         <li>Windows.SysColor.COLOR_BTNTEXT: hex-color-string
       *         <li>Windows.SysColor.COLOR_CAPTIONTEXT: hex-color-string
       *         <li>Windows.SysColor.COLOR_DESKTOP: hex-color-string
       *         <li>Windows.SysColor.COLOR_GRADIENTACTIVECAPTION: hex-color-string
       *         <li>Windows.SysColor.COLOR_GRADIENTINACTIVECAPTION: hex-color-string
       *         <li>Windows.SysColor.COLOR_GRAYTEXT: hex-color-string
       *         <li>Windows.SysColor.COLOR_HIGHLIGHT: hex-color-string
       *         <li>Windows.SysColor.COLOR_HIGHLIGHTTEXT: hex-color-string
       *         <li>Windows.SysColor.COLOR_HOTLIGHT: hex-color-string
       *         <li>Windows.SysColor.COLOR_INACTIVEBORDER: hex-color-string
       *         <li>Windows.SysColor.COLOR_INACTIVECAPTION: hex-color-string
       *         <li>Windows.SysColor.COLOR_INACTIVECAPTIONTEXT: hex-color-string
       *         <li>Windows.SysColor.COLOR_INFOBK: hex-color-string
       *         <li>Windows.SysColor.COLOR_INFOTEXT: hex-color-string
       *         <li>Windows.SysColor.COLOR_MENU: hex-color-string
       *         <li>Windows.SysColor.COLOR_MENUHILIGHT: hex-color-string
       *         <li>Windows.SysColor.COLOR_MENUBAR: hex-color-string
       *         <li>Windows.SysColor.COLOR_MENUTEXT: hex-color-string
       *         <li>Windows.SysColor.COLOR_SCROLLBAR: hex-color-string
       *         <li>Windows.SysColor.COLOR_WINDOW: hex-color-string
       *         <li>Windows.SysColor.COLOR_WINDOWFRAME: hex-color-string
       *         <li>Windows.SysColor.COLOR_WINDOWTEXT: hex-color-string
       *     </ul>
       *     <li>Windows 10 theme colors (as reported by UISettings, introduced in Windows 10 build 10240):
       *     <ul>
       *         <li>Windows.UI.ViewManagement.UISettings.ColorValue_Background: hex-color-string
       *         <li>Windows.UI.ViewManagement.UISettings.ColorValue_Foreground: hex-color-string
       *         <li>Windows.UI.ViewManagement.UISettings.ColorValue_AccentDark3: hex-color-string
       *         <li>Windows.UI.ViewManagement.UISettings.ColorValue_AccentDark2: hex-color-string
       *         <li>Windows.UI.ViewManagement.UISettings.ColorValue_AccentDark1: hex-color-string
       *         <li>Windows.UI.ViewManagement.UISettings.ColorValue_Accent: hex-color-string
       *         <li>Windows.UI.ViewManagement.UISettings.ColorValue_AccentLight1: hex-color-string
       *         <li>Windows.UI.ViewManagement.UISettings.ColorValue_AccentLight2: hex-color-string
       *         <li>Windows.UI.ViewManagement.UISettings.ColorValue_AccentLight3: hex-color-string
       *     </ul>
       * </ol>
       * {@code hex-color-string} is a value that can be parsed by
       * {@link javafx.scene.paint.Color#web(String)}
       */
      public interface Theme {
          /**
           * The list of stylesheet URLs that comprise this theme.
           * The ordering of the stylesheet URLs in this list is the
           * order in which the stylesheets are applied.
           */
          ObservableList<String> getStylesheets();
      
          /**
           * Occurs when the platform theme has changed.
           * This method always reports the full set of platform theme
           * properties, not only the properties that have changed.
           *
           * @param properties theme properties reported by the platform
           */
           void platformThemeChanged(Map<String, String> properties);
      }

      In javafx.application.Application, redefine the theme constants:

      public static final String STYLESHEET_CASPIAN =
          "theme:" + Caspian.class.getName();
      public static final String STYLESHEET_MODENA =
          "theme:" + Modena.class.getName();

        Attachments

          Activity

            People

            Assignee:
            mstrauss Michael Strauß
            Reporter:
            mstrauss Michael Strauß
            Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

              Dates

              Created:
              Updated:
              Resolved: