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
