Clean SuggestBox documentation and API

[dankurka]

Originally reported on Google Code with ID 7318

Found in GWT Release (e.g. 2.4.0, 2.5.0 RC):
2.4.0

Detailed description (please be as specific as possible):

1) from the SuggestBox class Javadoc:

"A SuggestBox fires SuggestionEvents whenever a suggestion is chosen, and handlers
for these events can be added using the addValueChangeHandler(ValueChangeHandler) method."

How can a ValueChangeHandler<String> receive a SuggestionEvent???

2) from the SuggestBox.addEventHandler(SuggestionHandler) method Javadoc:

"addEventHandler(SuggestionHandler handler) 
Deprecated. use addSelectionHandler(com.google.gwt.event.logical.shared.SelectionHandler)
instead."

So, should I need to add a ValueChangeHnadler or a SelectionHandler?

3) from the SuggestOracle.Suggestion class Javadoc:

"To access a suggestion's DTO when the suggestion is selected, add a ChangeHandler
to the SuggestBox (see SuggestBox's documentation for more information)."

So, a ValueChangeHandler, a SelectionHandler or a ChangeHandler???
Moreover, you can't add a ChangeHandler to a SuggestBox, but only on its TextBox.

4) more from the SuggestOracle.Suggestion class Javadoc:

"In the SuggestionHandler.onSuggestionSelected(SuggestionEvent event) method, obtain
the selected Suggestion object from the ChangeHandler object, and downcast the Suggestion
object to the subinterface."

!? How can I get a Suggestion object from a ChangeHandler within the implementation
of SuggestionHandler.onSuggestionSelected(SuggestionEvent event)? And, wait a moment...
a SuggestionHandler? Wasn't it a ValueChangeHandler rather than a SelectionHandler
rather than ChangeHandler?

5) more seriously, the "solution" is to ad a SelectionHandler, since SuggestBox implements
HasSelectionHandlers<SuggestOracle.Suggestion> and so it fires SelectionEvent<SuggestOracle.Suggestion>
events. However, I think that what is described in "Associating Data Transfer Objects
(DTOs) with Suggestion Objects" section of SuggestOracle.Suggestion Javadoc, which
is exactly what I need to do (I think it's a very common problem) is quite useless
unless SelectionEvent<SuggestOracle.Suggestion> events are fired only when the user
explicitely selects a suggestion from the suggestion list. In fact, the user can just
finish entering the desired text without choosing any suggestion. In this case, I think
that if the user has written something that perfectly matches a suggestion (based on
some customizable criteria), an event should be fired too, for instance when the user
hits ENTER on the TextBox or moves the focus. Otherwise, any logic that kicks in only
after a suggestion has been explicitly chosen can't be used to fully validate the user
input.

Reported by mauromol@tiscali.it on 2012-04-14 16:50:17

[dankurka]

Issue 4575 mentions number one.

Reported by tuckerpmt on 2012-07-31 12:29:30

[dankurka]

Reported by dankurka@google.com on 2013-06-05 14:09:17

• Status changed: PatchesWelcome

[dankurka]

Points from 1 to 4 fixed with gerrit patch: https://gwt-review.googlesource.com/5216

Reported by defaveri on 2013-10-30 18:30:47