Discussion: Naming API method

[Kevin Rushforth]

My initial reaction is that I like the name "activeWhen" at least as 
well as any of the alternatives discussed so far. It's less wordy than 
"observedWhen" (which I suggested), and probably easier to describe. I 
don't really care for using the term "scope".

I also think "when" or "whenever" are acceptable, but I know some don't 
like them.

I think the leading candidates are:

activeWhen
whenever
when
observedWhen

Unless someone can come up with a better name that can be easily 
described, I recommend picking one of these.

-- Kevin


On 11/21/2022 2:36 PM, Michael Strauß wrote:
> Thanks for your clarifications.
> Maybe the actual problem is that we don't have a good name for "gets
> the current value, but doesn't subscribe to updates".
> We could call bindings "active" when changes of the source value are
> processed, and "inactive" if the binding exists, but doesn't process
> changes.
> With a documented definition of "active", the method could simply be
> named `activeWhen`.
>
>
> On Mon, Nov 21, 2022 at 10:57 PM John Hendrikx <john.hendrikx at gmail.com> wrote:
>> Hi Michael,
>>
>> Thanks for your suggestion.
>>
>> The effect is not quite what you describe however, as the initial value
>> when the operation is first invoked is retained. It's true however that
>> when the condition is always `false` that the value will be a constant,
>> and that when it is always `true` it effectively is just a duplicate of
>> the left hand observable.  Let me illustrate:
>>
>>       public static void main(String[] args) {
>>         StringProperty sp = new SimpleStringProperty("foo");
>>         BooleanProperty active = new SimpleBooleanProperty(false); //
>> inactive
>>         ObservableValue<String> x = sp.when(active);  // holds "foo"
>> despite being inactive
>>
>>         System.out.println(x.getValue());  // prints "foo"
>>
>>         sp.set("bar");
>>
>>         System.out.println(x.getValue());  // still prints "foo"
>>
>>         active.set(true);
>>
>>         System.out.println(x.getValue());  // prints "bar"
>>       }
>>
>> This behavior doesn't violate the rule that the new binding shouldn't
>> observe its source when the condition is false as no listener was
>> involved to get the initial value.  The initial value is important as
>> all bindings must have some kind of value. The docs do describe this in
>> the first sentence:
>>
>> "Returns an {@code ObservableValue} that holds this value and is updated
>> only when {@code condition} holds {@code true}"
>>
>> I think `withScope` could work (or `scopedTo`) but not sure if "scope"
>> itself is a good description -- we'd need to update the description to
>> use the word scope in a way that makes clear what it does preferably
>> without having to resort to "updated only when" or "only observes when":
>> ie: "Returns an ObservableValue that is scoped to the given condition" ?
>>
>> --John