RFR: 8290040: Provide simplified deterministic way to manage listeners [v6]

[John Hendrikx]

On Tue, 25 Oct 2022 21:50:50 GMT, Nir Lisker <nlisker at openjdk.org> wrote:

>> modules/javafx.graphics/src/main/java/javafx/scene/Node.java line 1415:
>> 
>>> 1413:      *
>>> 1414:      * <p>Note that the {@code Node} does not need to be visible for this property
>>> 1415:      * to be {@code true}.
>> 
>> I think that the definition of "shown" is important enough to make it the main focus of the description with something like:
>> 
>> 
>> Indicates whether or not this {@code Node} is shown. A node is considered shown if it's
>> part of a {@code Window} whose {@link shown #Window::showingProperty} is {@code true}.
>> The {@link visibility #visibleProperty} of the node or its scene do not affect this property.
>> 
>> 
>> I think that there's no need to repeat the showing conditions for a window.
>> Also we need to be careful not to confuse `shown` with `showing`, which are properties on `ComboBox`, `ChoiceBox` and others.
>
> We might also want to add a paragraph explaining its use. Something like:
> 
> This property can be used in conjunction with {@link ObservableValue#when}
> as a source for listeners that should be collected when the node is not shown.
> 
> If there are other uses we can mention them as well.

I've changed the documentation as you suggested, and I also included that the `Node` must be part of a `Scene`, although I suppose that is a given since you can't show a node in a window otherwise.

> Also we need to be careful not to confuse shown with showing, which are properties on ComboBox, ChoiceBox and others.
Definitely, I had `showing` in the initial version only to discover it was already present in common controls.

I also added your suggested paragraph but rephrased as:

> This property can be used in conjunction with {@link ObservableValue#when} to create bindings which are only actively listening to their source when the node is shown.

Other uses could be to disable animations when not shown.  For example, `ProgressBarSkin` and some other controls only animate their controls when visible (they however do a visibility check as well).  See `isTreeShowing`.  

For example, I've used this property to start animations as soon as a `Node` becomes shown, and to stop the animation when it is no longer shown.  I've added this to the docs:

> This property can also be used to start animations when the node is shown, and to stop them when it is no longer shown.

I also added a `@see ObservableValue#when(ObservableValue)` -- not sure if that is needed.

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

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