RFR: 8263095: Provide a way for a custom control to indicate that its userAgentStyleSheet has changed

[Alessandro Parisi]

>
> The next steps would be to send an email (you can reply to this thread),
> with a clear description of your proposal.
>
> The focus should be on what problem you are solving and on the proposed
> public API and behavioral changes. I suggest not (yet) referring to code
> changes in your PR except for illustrative purposes. Start with what the
> current behavior is, what problem that is causing, and what your
> proposed solution is. By way of a counter-example, the "computeIfAbsent"
> code fragment you included in your email and PR description is an
> implementation detail; the concept that should be discussed is the
> presumed stability of a Region's userAgentStyleSheet. This presumed
> stability is documented in the spec, so start there, not with the code.
>
> If there is general agreement that this feature is a good thing to add
> to JavaFX as public API, meaning it is something that would benefit
> multiple app developers, the next step would be to review the proposed
> API and behavioral changes. This can be done in the context of reviewing
> the PR. The focus during this phase of review would be mainly on the
> specification changes that would need to go into the API docs and be
> included in the CSR.
>
> The above is good general guidance for getting any new non-trivial
> feature added to the JavaFX API.
>
> As for the specifics of what you are proposing, the main things I would
> like to see addressed during the initial discussion are:
>
> * When and why do custom controls typically want to provide a dynamic
> userAgentStylesheet?
> * How should a control indicate that its userAgentStyleSheet is dynamic?
> By a separate property (read-only?) that it provides as an override?
> Should it be dynamic by default (I am skeptical, myself)?
> * Does an application that uses a custom control need to know whether or
> not that control uses a dynamic userAgentStylesheet? Can it affect the
> answer (e.g., you mentioned theming, can you be more specific)?
>
> -- Kevin
>

So, without talking about code, I'm going to explain what I want to achieve
with this change.

As of now, custom controls  can specify their userAgentStylesheet by
overriding the getter inherited from Region. The documentation says:

> An implementation may specify its own user-agent styles for this Region,
> and its children, by overriding this method. Subclasses overriding this
> method should not assume any particular implementation approach as to the
> number and frequency with which it is called. For this reason, attempting
> any kind of dynamic implementation (i.e. returning different user agent
> stylesheet values) based on some state change is highly discouraged, as
> there is no guarantee when, or even if, this method will be called.
>

The issue there is that the current implementation is not dynamic.
To answer your first question:

> When and why do custom controls typically want to provide a dynamic
> userAgentStylesheet?
>

In my library, I currently have two custom controls. For each of them I
have three stylesheets and I want the user  to choose the style they
prefer. So, the control is one, but the styles are three, and I can only
provide one userAgentStylesheet because it is not dynamic. The solution
would be to create three different controls and each of them uses one of
the three stylesheets. However, this would lead to code duplication for
just a stylesheet change.

To answer the third question:

> Does an application that uses a custom control need to know whether or
> not that control uses a dynamic userAgentStylesheet? Can it affect the
> answer (e.g., you mentioned theming, can you be more specific)?
>

Keeping in mind what I said above, let's suppose the user is developing an
app with dark theme as default. With a dynamic implementation of the
userAgentStylesheet I could specify two or more stylesheets for my custom
controls, one or more for light and dark styles, the user would just need
to change the style. That's what I mean by theming. In my custom controls
then I could specify a way to change the style (an enumerator for example).
It's up to the user then to decide which style to use.
So the control needs to specify a way to change the style and that's up to
the library developer to decide how (like I said an enumerator would be a
way to do it), and JavaFX must allow the control to change the userAgent
dynamically and update the control on change.

To answer your second question:

> How should a control indicate that its userAgentStyleSheet is dynamic?
>

Using a property. Rather than just having a getter, we could introduce a
property to store the userAgent.
When the user changes the style, the property changes too. On change, the
StyleManager should also be notified about the change so that the CSS can
be recomputed