Package limn.scene

Class SystemPreferences

java.lang.Object
limn.scene.SystemPreferences
public final class SystemPreferences extends Object
Three preferences the user sets for every application on their desktop: a light or dark appearance, less motion, and more contrast. The backend reads them from the platform and reports them here; an application reads current() and follows changes with observeChanges(java.lang.Runnable).

The toolkit reports; the application decides. A dark system does not switch an application's theme, because which palette to use is the application's choice, and its theme may be its brand. Following the system is one line: 


 SystemPreferences.observeChanges(() -> pickTheme(SystemPreferences.current()).apply());

The one preference the toolkit acts on by itself is reduceMotion(): while it is set, a Transition finishes at once and popups and dialogs open and close without fading; see Motion.

What each platform answers: on macOS the application's effective appearance and the accessibility display options; on Windows the apps' light-theme setting, client-area animation and high contrast; on Linux the desktop portal's appearance settings, with GNOME's enable-animations where the portal has no reduced-motion key. A platform that cannot say reports SystemPreferences.ColorScheme.NO_PREFERENCE and false, as Ubuntu's default appearance does.

The toolkit also follows underlineAccessKeys(): while it is set, the access letters of menus, buttons and labels stay underlined, where otherwise they show only while Alt is held. Windows answers it (the keyboard setting to underline access keys); the other systems report false.

A class and not a record, with no public constructor: only a backend builds one. A record's constructor and its deconstruction pattern would have made the four preferences of today a contract, so that a fifth, which a system may offer in a later 1.x release, could not be added without breaking every caller that builds or deconstructs one. An application reads the accessors, compares two values with equals(java.lang.Object), and starts from NONE.

  • Field Details

    • NONE

      public static final SystemPreferences NONE
      No preference, no reduced motion, no increased contrast, access keys underlined only while Alt is held: what a platform that says nothing reports.

  • Method Details

    • colorScheme

      public SystemPreferences.ColorScheme colorScheme()
      Returns:
      the appearance the user chose, or SystemPreferences.ColorScheme.NO_PREFERENCE

    • reduceMotion

      public boolean reduceMotion()
      Returns:
      whether the user asked for less motion

    • increaseContrast

      public boolean increaseContrast()
      Returns:
      whether the user asked for more contrast

    • contrastColors

      public @Nullable SystemPreferences.ContrastColors contrastColors()
      Returns:
      the palette the user chose for more contrast where the platform has one (a Windows contrast theme, while increaseContrast() is true); null elsewhere, where more contrast keeps the application's palette and strengthens it

    • underlineAccessKeys

      public boolean underlineAccessKeys()
      Returns:
      whether the user asked for access keys to be underlined at all times; false on every system but Windows

    • equals

      public boolean equals(@Nullable Object o)
      Equal when every preference is: what report(limn.scene.SystemPreferences) compares to tell a change.
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Every preference by name, for a log line.
      Overrides:
      toString in class Object

    • current

      public static SystemPreferences current()
      Returns:
      the preferences the backend last reported, or NONE before any backend did. Any thread.

    • observeChanges

      public static Subscription observeChanges(Runnable listener)
      Subscribes to changes. A listener runs on the UI thread once per change of the value, however many signals the platform sent for it.
      Parameters:
      listener - what to run when the preferences change
      Returns:
      a handle that unsubscribes; cancelling it twice is a no-op. UI thread

    • report

      public static void report(SystemPreferences preferences)
      Reports what the platform says now. A backend calls it when it starts and whenever the platform signals a change, and NONE when it closes; a test calls it to put back what it found in current(). Listeners run only when the value differs from the current one. UI thread only.
      Parameters:
      preferences - what the platform says; never null
      Throws:
      NullPointerException - if preferences is null