RFR: 8290844: Add Skin.install() method [v3]

[Andy Goryachev]

On Wed, 7 Sep 2022 19:06:29 GMT, Kevin Rushforth <kcr at openjdk.org> wrote:

>> @throws IllegalArgumentException if {@link Skin#getSkinnable()} returns a different {@code Skinnable}
>> 
>> is this better?
>
> As discussed elsewhere, only the property method should have javadoc comments, so this should be moved up to the property method, and the existing javadoc comments for this method should be deleted.
> 
> I think we need a clearer statement here, given that there are only two top-level classes that implement `Skinnable`, `Control` and `PopupControl`, and thus override this method. `Control` enforces the 1-to-1 relationship by throwing an IAE if the `Skinnable` of the `Skin` doesn't match the `Control`, while `PopupControl` does not.
> 
> So maybe something a little more definitive, like this?
> 
> 
>      * To ensure a one-to-one relationship between a {@code Skinnable} and its
>      * {@code Skin}, some implementations of this method will check the return value of
>      * {@link Skin#getSkinnable()} against this Skinnable,
>      * and throw an {@code IllegalArgumentException} if it is not the same.
> 
> 
> And then the exception could be changed to say....
> 
> 
>      * @throws IllegalArgumentException if {@code skin.getSkinnable() != this}, for
>      * implementations that enforce this restriction
> 
> 
> This information would then be repeated in the `Control` class, but without the qualification.

also updated Control skinProperty javadoc, please review.

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

PR: https://git.openjdk.org/jfx/pull/845