/*
* Copyright 2008 Google Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy of
* the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations under
* the License.
*/
package com.google.gwt.user.client.ui;
import com.google.gwt.user.client.rpc.IsSerializable;
import java.util.ArrayList;
import java.util.Collection;
/**
* A {@link com.google.gwt.user.client.ui.SuggestOracle} can be used to create
* suggestions associated with a specific query string. It is currently used by
* {@link SuggestBox}.
*
* @see SuggestBox
*/
public abstract class SuggestOracle {
private Response emptyResponse = new Response(new ArrayList<Suggestion>());
/**
* Callback for {@link com.google.gwt.user.client.ui.SuggestOracle}. Every
* {@link Request} should be associated with a callback that should be called
* after a {@link Response} is generated.
*/
public interface Callback {
/**
* Consume the suggestions created by a
* {@link com.google.gwt.user.client.ui.SuggestOracle} in response to a
* {@link Request}.
*
* @param request the request
* @param response the response
*/
void onSuggestionsReady(Request request, Response response);
}
/**
* A {@link com.google.gwt.user.client.ui.SuggestOracle} request.
*/
public static class Request implements IsSerializable {
private int limit = 20;
private String query;
/**
* Constructor for {@link Request}.
*/
public Request() {
}
/**
* Constructor for {@link Request}.
*
* @param query the query string
*/
public Request(String query) {
setQuery(query);
}
/**
* Constructor for {@link Request}.
*
* @param query the query string
* @param limit limit on the number of suggestions that should be created
* for this query
*/
public Request(String query, int limit) {
setQuery(query);
setLimit(limit);
}
/**
* Gets the limit on the number of suggestions that should be created.
*
* @return the limit
*/
public int getLimit() {
return limit;
}
/**
* Gets the query string.
*
* @return the query string
*/
public String getQuery() {
return query;
}
/**
* Sets the limit on the number of suggestions that should be created.
*
* @param limit the limit
*/
public void setLimit(int limit) {
this.limit = limit;
}
/**
* Sets the query string used for this request.
*
* @param query the query string
*/
public void setQuery(String query) {
this.query = query;
}
}
/**
* {@link com.google.gwt.user.client.ui.SuggestOracle} response.
*
* <p>Can optionally have truncation information provided. To indicate that
* there are more results but the number is not known, use:
*
* <p><code>response.setMoreSuggestions(true);</code>
*
* <p>Or to indicate more results with an exact number, use:
*
* <p><code>response.setMoreSuggestionsCount(102);</code>
*/
public static class Response implements IsSerializable {
private Collection<? extends Suggestion> suggestions;
/**
* The response is considered to have "more suggestions" when the number of
* matching suggestions exceeds {@link Request#getLimit}, so the response
* suggestion list is truncated.
*/
private boolean moreSuggestions = false;
/**
* Number of truncated suggestions.
*/
private int numMoreSuggestions = 0;
/**
* Constructor for {@link Response}.
*/
public Response() {
}
/**
* Constructor for {@link Response}.
*
* @param suggestions each element of suggestions must implement the
* {@link Suggestion} interface
*/
public Response(Collection<? extends Suggestion> suggestions) {
setSuggestions(suggestions);
}
/**
* Gets how many more suggestions there are.
*
* @return the count. if there no more suggestions or the number of more
* suggestions is unknown, returns 0.
*/
public int getMoreSuggestionsCount() {
return this.numMoreSuggestions;
}
/**
* Gets the collection of suggestions. Each suggestion must implement the
* {@link Suggestion} interface.
*
* @return the collection of suggestions
*/
public Collection<? extends Suggestion> getSuggestions() {
return this.suggestions;
}
/**
* Gets whether or not the suggestion list was truncated due to the
* {@link Request#getLimit}.
*/
public boolean hasMoreSuggestions() {
return this.moreSuggestions;
}
/**
* Sets whether or not the suggestion list was truncated due to the
* {@link Request#getLimit}.
*/
public void setMoreSuggestions(boolean moreSuggestions) {
this.moreSuggestions = moreSuggestions;
}
/**
* Sets whether or not the suggestion list was truncated due to the
* {@link Request#getLimit}, by providing an exact count of remaining
* suggestions.
*
* @param count number of truncated suggestions. Pass 0 to indicate there
* are no other suggestions, which is equivalent to
* {@link #setMoreSuggestions(boolean) setMoreSuggestions(false)}.
*/
public void setMoreSuggestionsCount(int count) {
this.numMoreSuggestions = count;
this.moreSuggestions = (count > 0);
}
/**
* Sets the suggestions for this response. Each suggestion must implement
* the {@link Suggestion} interface.
*
* @param suggestions the suggestions
*/
public void setSuggestions(Collection<? extends Suggestion> suggestions) {
this.suggestions = suggestions;
}
}
/**
* Suggestion supplied by the
* {@link com.google.gwt.user.client.ui.SuggestOracle}. Each suggestion has a
* display string and a replacement string. The display string is what is
* shown in the SuggestBox's list of suggestions. The interpretation of the
* display string depends upon the value of its oracle's
* {@link SuggestOracle#isDisplayStringHTML()}. The replacement string is the
* string that is entered into the SuggestBox's text box when the suggestion
* is selected from the list.
*
* <p>
* Replacement strings are useful when the display form of a suggestion
* differs from the input format for the data. For example, suppose that a
* company has a webpage with a form which requires the user to enter the
* e-mail address of an employee. Since users are likely to know the name of
* the employee, a SuggestBox is used to provide name suggestions as the user
* types. When the user types the letter <i>f</i>, a suggestion with the
* display string <i>foo bar</i> appears. When the user chooses this
* suggestion, the replacement string, <i>foobar@company.com</i>, is entered
* into the SuggestBox's text box.
* </p>
*
* <p>
* This is an example where the input data format for the suggestion is not as
* user-friendly as the display format. In the event that the display of a
* suggestion exactly matches the input data format, the
* <code>Suggestion</code> interface would be implemented in such a way that
* the display string and replacement string would be identical.
* </p>
*
* <h3>Associating Data Transfer Objects (DTOs) with Suggestion Objects</h3>
* Some applications retrieve suggesstions from a server, and may want to send
* back a DTO with each suggestion. In the previous example, a DTO returned
* with the suggestion may provide additional contact information about the
* selected employee, and this information could be used to fill out other
* fields on the form. To send back a DTO with each suggestion, extend the
* <code>Suggestion</code> interface and define a getter method that has a
* return value of the DTO's type. Define a class that implements this
* subinterface and use it to encapsulate each suggestion.
*
* <p>
* To access a suggestion's DTO when the suggestion is selected, add a
* {@link com.google.gwt.event.dom.client.ChangeHandler} to the SuggestBox
* (see SuggestBox's documentation for more information). In the
* <code>SuggestionHandler.onSuggestionSelected(SuggestionEvent event)</code>
* method, obtain the selected <code>Suggestion</code> object from the
* {@link com.google.gwt.event.dom.client.ChangeHandler} object, and downcast
* the <code>Suggestion</code> object to the subinterface. Then, acces the DTO
* using the DTO getter method that was defined on the subinterface.
* </p>
*/
public interface Suggestion {
/**
* Gets the display string associated with this suggestion. The
* interpretation of the display string depends upon the value of its
* oracle's {@link SuggestOracle#isDisplayStringHTML()}.
*
* @return the display string for this suggestion
*/
String getDisplayString();
/**
* Gets the replacement string associated with this suggestion. When this
* suggestion is selected, the replacement string will be entered into the
* SuggestBox's text box.
*
* @return the string to be entered into the SuggestBox's text box when this
* suggestion is selected
*/
String getReplacementString();
}
/**
* Constructor for {@link com.google.gwt.user.client.ui.SuggestOracle}.
*/
public SuggestOracle() {
}
/**
* Should {@link Suggestion} display strings be treated as HTML? If true, this
* all suggestions' display strings will be interpreted as HTML, otherwise as
* text.
*
* @return by default, returns false
*/
public boolean isDisplayStringHTML() {
return false;
}
/**
* Generate a {@link Response} based on a default request. The request query
* must be null as it represents the results the oracle should return based on
* no query string.
* <p>
* After the {@link Response} is created, it is passed into
* {@link Callback#onSuggestionsReady(com.google.gwt.user.client.ui.SuggestOracle.Request, com.google.gwt.user.client.ui.SuggestOracle.Response)}
* .
* </p>
*
* @param request the request
* @param callback the callback to use for the response
*/
public void requestDefaultSuggestions(Request request, Callback callback) {
assert (request.query == null);
callback.onSuggestionsReady(request, emptyResponse);
}
/**
* Generate a {@link Response} based on a specific {@link Request}. After the
* {@link Response} is created, it is passed into
* {@link Callback#onSuggestionsReady(com.google.gwt.user.client.ui.SuggestOracle.Request, com.google.gwt.user.client.ui.SuggestOracle.Response)}.
*
* @param request the request
* @param callback the callback to use for the response
*/
public abstract void requestSuggestions(Request request, Callback callback);
}