13.0p+ Persistent hover API

[Blama]

Hi Isomorphic,

I checked yesterday if Persistent Hovers (v13.0p_2024-02-21) are also available in 12.1p I'm using (they are not).
While doing so I checked the functionality and the sample code. It seems that the setHoverFocusKey() the sample uses is not documented, see here, only the property hoverFocusKey seems to exist.

Best regards
Blama

[Isomorphic]

Note the "IRW" flags on the hoverFocusKey docs. Hover over that - it explains what the flags mean. The "W" implies the property is settable dynamically, and there isn't always separate doc for the setter.

[Blama]

Hi Isomorphic,

I'm pretty sure I read somewhere in the forums that one should always use the special setter, if it exists. The setProperty() docs say a similar thing and the Flags documentation (see picture) that you mentioned say that in a even stronger tone.
So how should one know that it exists, if it is not docd? Also, it is docd for SmartGWT.
This is the first time I have come along this situation. Am I missing something?

Best regards
Blama

[Isomorphic]

You don't actually need to know whether it exists, since setProperty() / setProperties() will find it automatically. But if you're curious for whatever reason, you can just check: isc.isA.Function(someCanvasInstance.possibleSetterName).

[Blama]

Hi Isomorphic,

it's great that both would work, but still your advice contradicts the IRW-Flag docs. These say "the method exists, and because it does, you must use it".
But then it should be doc'd. While the isc.isA.Function()-way will work, this is not really feasible, and then one does not know about the setter.

So IMHO either the IRW-Flag docs and other advice in the same direction is worded too strongly or the method should be doc'd.
And also the method exists in SmartGWT, so this is really really strange IMHO.

Best regards
Blama

[Isomorphic]

So, again, as we just mentioned, setProperty() / setProperties() will find the setter. So if you just call setProperty() / setProperties() you are calling the setter and you don't even need to care whether it exists or not.

[Blama]

Hi Isomorphic,

OK, understood. setProperty() does the work for me of finding and calling the setter and I'd be fine with just it.

But then the W-docs in the flags explanation and the setProperty()-docs are wrong or at least very misleading.

Flags:

"writable": property can be written to after initialization. If a setter method exists, it must be called. If no setter method exists, setProperty() must be called.

Class.setProperty():

setProperty (propertyName, newValue)
Set a property on this object, calling the setter method if it exists.

Whenever you set a property on an ISC component, you should call either the specific setter for that property, or setProperty()/setProperties() if it doesn't have one. This future-proofs your code against the later addition of required setters.

Nowhere it says that just using setProperty() is the way to go. Both docs actually say "Call a setter if it is there, setProperty() otherwise". And the Flags docs even use the word "must".

This started as me noting that the Canvas.setHoverFocusKey() API that is used in the sample code is actually not doc'd in SmartClient. And this plus the docs as they are today does still make me think that the method should be doc'd. This is how it all started.

Good to know that the setProperty()-way also works, though, because it looks for the setter. And I see the future-proofing of this vs. just assigning the property as well.

Best regards
Blama

[Isomorphic]

This is possibly just a different use of language (both in terms of Java vs JavaScript, and maybe in terms of spoken languages), but to us, when we say the setter must be called, and that setProperty() calls it for you, that's it, there's nothing left to clarify.

In particular, the important thing is that the functionality in the setter is invoked (not whether you call it directly) and it is hard to see how anyone could read the docs and do something invalid.

So we don't plan to change anything here in the docs - we'll wait to see if we get a second instance of someone finding this confusing.

[Blama]

Hi Isomorphic,

In particular, the important thing is that the functionality in the setter is invoked (not whether you call it directly) and it is hard to see how anyone could read the docs and do something invalid.

Agreed.

but to us, when we say the setter must be called, and that setProperty() calls it for you, that's it, there's nothing left to clarify.

Yes, that's what you say in this thread. The docs say it differently IMHO (and I assume the code of setProperty() is considered an implementation detail that could change anytime), but whatever, as the 1st quote says, there won't be ill effects either way currently.

The last thing then is why the API setHoverFocusKey() is not doc'd in SmartClient only and why it is used in the sample code, when it is not doc'd.

Best regards
Blama

[Isomorphic]

For completeness, no, the behavior of setProperty() is not considered "an implementation detail that could change anytime" because it's documented. That's the purpose of the documentation: to tell you what you can rely upon.