RFR: 8301302: Platform preferences API [v3]

[Andy Goryachev]

On Thu, 2 Feb 2023 19:54:33 GMT, Michael Strauß <mstrauss at openjdk.org> wrote:

>> Please read [this document](https://gist.github.com/mstr2/9f46f92c98d3c86aa6a0b4224a9a6548) for an introduction to the Platform Preferences API, and how it interacts with the proposed style theme and stage appearance features.
>
> Michael Strauß has updated the pull request with a new target base due to a merge or a rebase.

catching up with the discussion:

1. ObservableMap.  Is it unmodifiable?  I'd expect it to be, since this API exposes the properties of the underlying platform.
2. Does this API track user changes (via OS widgets such as Control Panel in Windows) at runtime?
3. "Platform Preferences" name.  We already have java.util.prefs.Preferences, the name might be confusing.  Swing has UIDefaults, perhaps we could think of something along those lines?
4. Re: Property API.  I think it is still a valid approach, once a call to list all the available keys is added.  It would be nice to have a way to also obtain the type of the value for a specific key, or infer the type from the type of property returned.  Even more, it might be nice to be able to query the:
- list of all the keys exposed by the API
- value type
- possibly, a human-readable description of the property
- possibly, whether the value can be changed by this application

I am still not sold on the concept of Appearance (what if a Dusk mode will be added in addition to the Dark and Light?).  However, it could be just another platform-specific key, could it not?

What do you think?

Also, this PR needs a CSR once everyone is happy with the outcome of this discussion.

[discussion] the problem with ObservableMap is that it drags in a large API surface of Map.

[discussion] A native window appearance might be more than one attribute.  In that sense, I think it is better to treat them as such - as platform-specific attributes.

(An example I have in mind is a gradient color accent in Windows 10 - I don't know if that's still a thing, or how it's done in windows 11 and the dark mode).  But the idea of limiting the API to a very narrow set of existing variants bothers me.

[question] when an application changes the value of one or more properties, does it change the appearance of that application alone, all of the javafx applications, or all of the platform applications?

[opinion] I'd rather see UIPreferences name (PlatformUISettings?) and move it outside of the Platform class.

[discussion]

> `Appearance` is central to _all_ of those features

>From the API perspective, Appearance, though important, is just one of many attributes.  Adding a separate method where we could operate with a Set of attributes ("hints") is, in my opinion, a less optimal solution.

For example, Stage.setAttributes(Set<?>) is a much more flexible approach.  If things change tomorrow with new attribute added, or some other change, this API does not have to be modified.  (The Stage should silently ignore any attributes it does not recognize or that are not supported by the platform).

For the Platform Preferences API, a native attribute such as `DWMWA_USE_IMMERSIVE_DARK_MODE`  may also be echoed by an Appearance attribute, so the app dev can use either one depending on the requirements. 

I suppose we could have a dedicated getAppearance() method as shortcut (as well as some other frequently used shortcuts).

What do you think?

[opinion]

I don't quite like the 'override' method and the idea of app modifying the values, as I see it as a purely informational API.  The changes should, in my opinion, be triggered by the platform only.  Any other functionality is app-specific.

Another thing i am not comfortable with is the eager initialization (and that's another reason I don't quite like ObservableMap idea).  Generally speaking, we should not be initializing things an application is not going to use.  That's why I like the concept of accessing individual attributes - if a theme needs Appearance, only that value and its machinery gets initialized.

Small delays added here and there add up.

-------------

PR Comment: https://git.openjdk.org/jfx/pull/1014#issuecomment-1520708740
PR Comment: https://git.openjdk.org/jfx/pull/1014#issuecomment-1520894055
PR Comment: https://git.openjdk.org/jfx/pull/1014#issuecomment-1520897723
PR Comment: https://git.openjdk.org/jfx/pull/1014#issuecomment-1520898504
PR Comment: https://git.openjdk.org/jfx/pull/1014#issuecomment-1520899926
PR Comment: https://git.openjdk.org/jfx/pull/1014#issuecomment-1523841849
PR Comment: https://git.openjdk.org/jfx/pull/1014#issuecomment-1523855676