On Tue, 25 Oct 2022 21:50:50 GMT, Nir Lisker <nlis...@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
