Discussion: Naming API method

[Kevin Rushforth]

While rereading the proposed docs for the new method, the following 
stood out to me:

"The returned ObservableValue only observes this value when condition 
holds true."

So I agree that "updateWhen" isn't really accurate, but I don't care for 
"onCondition" either.

I think "whenever" would be OK, but what about "observesWhen" (or maybe 
"observedWhen") as a name?

-- Kevin


On 11/14/2022 9:47 AM, Andy Goryachev wrote:
>
> I'd pick "whenever" or "onCondition".
>
> "updateWhen" sounds like an update, which I think it is not.  "when" 
> seems too vague.
>
> Disclaimer: English is not my native language.
>
> -andy
>
> *From: *openjfx-dev <openjfx-dev-retn at openjdk.org> on behalf of Kevin 
> Rushforth <kevin.rushforth at oracle.com>
> *Date: *Monday, 2022/11/14 at 09:40
> *To: *openjfx-dev at openjdk.org <openjfx-dev at openjdk.org>
> *Subject: *Re: Discussion: Naming API method
>
> I also think this will be a useful feature to get into JavaFX.
>
> As for the name of the method, the only one of them I don't like is
> "conditionOn". That name doesn't suggest (to me anyway) what its purpose
> is. I think any of the ones with "when" in the name would work. I have a
> slight preference for "updateWhen", but could be talked into one of the
> others.
>
> -- Kevin
>
>
> On 11/14/2022 6:52 AM, John Hendrikx wrote:
> > Hi,
> >
> > I'm working on https://github.com/openjdk/jfx/pull/830 where I asked
> > for some opinions on the naming of a new method I'd like to introduce
> > in ObservableValue.
> >
> > I wrote a (perhaps too large) comment about the possible names and
> > rationales:
> > https://github.com/openjdk/jfx/pull/830#issuecomment-1304846220
> >
> > I'd like to ask what others think what would be a good name for this
> > new method (Observable#when in the PR) in order to move the PR
> > forward, as I think it offers a very compelling feature to JavaFX
> > (moving from weak reference to deterministic behavior when it comes to
> > listener management).  My opinion has always been that using weak
> > listeners for listener management is a crutch that relies far too much
> > on the internal workings of the JVM and Garbage Collector which offer
> > no guarantees as to the timely clean up of these references and the
> > listeners related to them.
> >
> > Leading contenders are (but not limited to these, if you have a better
> > name):
> >
> > 1) conditionOn
> >
> > 2) updateWhen
> >
> > 3) when
> >
> > 4) whenever
> >
> > Usage in code is nearly always going to be something like these
> > constructs:
> >
> >       // keeps text property in sync with longLivedProperty when label
> > is shown:
> > 
> label.textProperty().bind(longLivedProperty.**when**(label::isShownProperty)); 
>
> >
> >
> >       // keeps text property in sync with longLivedProperty when
> > container is shown:
> > 
> label.textProperty().bind(longLivedProperty.**when**(container::isShownProperty));
> >
> >
> > It can also be used to make a listener only actively listen when a
> > condition is met (the listener is added/removed immediately when the
> > condition changes, facilitating GC):
> >
> >       // listen to changes of longLivedProperty when container is shown:
> > longLivedProperty.when(container::isShownProperty)
> >             .addListener((obs, old, current) -> { ... change listener
> > ... });
> >
> > Or it can be used to disable updates temporarily (or permanently):
> >
> >         BooleanProperty allowUpdates = new SimpleBooleanProperty(true)
> >
> >         // keeps text property in sync when updates are allowed:
> > name.textProperty().bind(model.title.when(allowUpdates));
> > detail.textProperty().bind(model.subtitle.when(allowUpdates));
> > 
> asyncImageProperty.imageHandleProperty().bind(model.imageHandle.when(allowUpdates));
> >
> >
> > This last example can be useful in Skin#dispose, but has uses outside
> > of skins as well, for example when you want to prevent updates until
> > things have settled down.
> >
> > Thanks for reading!
> >
> > --John
> >
> >
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/openjfx-dev/attachments/20221115/41a33826/attachment-0001.htm>