Platform preferences API

[Michael Strauß]

See also Andy's question:
> Is high contrast mode encoded as another attribute, or does it need two more values in Appearance (high contrast light, high contrast dark)?

LIGHT and DARK are the only two appearances afforded by Windows
(starting with Windows 10), macOS, and iOS. I think it's safe to say
that the light/dark distinction is here to stay for the forseeable
future.
We probably shouldn't over-engineer this aspect, especially not by
introducing additional appearances like "high contrast light" or "high
contrast dark".
Keeping this simple allows us to nicely integrate two different APIs:
    stage.appearanceProperty().bind(Application.getPreferences().appearanceProperty());

If an application wants to support additional themes (high-contrast or
entirely custom themes), it can do so with the upcoming StyleTheme
API.

Having Appearance be an enumeration also allows us to add additional
constants if this were to become necessary in the future.
I've thought about using sealed interfaces to allow applications to
potentially provide their own Appearance implementation:

sealed interface Apperance permits Light, Dark {
    ...
    non-sealed interface Light extends Appearance {}
    non-sealed interface Dark extends Appearance {}
}

This would allow us to encode more bits of information in an
Appearance. For example, applications could encode platform-specific
hints like corner roundness.
But the downside of this is that it's now harder to switch on the
light/dark appearance bit.

I think it's more sensible to distinguish between three different
types of knobs that authors can use to control the look&feel of their
application:

1. Knobs that significantly affect the window border and the window content
2. Knobs that significantly affect only the window border
3. Knobs that affect OS-specific details of the window border

The first category is represented by Appearance, that's why it gets to
have its own enumeration.
The second category is represented by StageStyle, because we have
broad support on most operating systems.
The third category is currently unrepresented, and it includes knobs
like DWM_WINDOW_CORNER_PREFERENCE, which is only available on Windows
11.
In the future, OS-specific stage details could be controlled with a
`Stage.hints` property, which also strongly implies that we are
dealing with optional details.

In general, we don't need Appearance be part of the first deliverable,
we can also add it later with the Stage Decorations RFE.


On Wed, Jun 14, 2023 at 8:48 PM Kevin Rushforth
<kevin.rushforth at oracle.com> wrote:
>
> 4. Is an Appearance enum the best way to provide the indication of LIGHT
> vs DARK? Do we need it as part of the Preferences API or should it wait
> until one of the later RFEs?
>