| /* |
| * 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.safehtml.shared.annotations.IsSafeHtml; |
| 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.logical.shared.SelectionHandler} to the SuggestBox |
| * (see SuggestBox's documentation for more information). In the |
| * <code>SelectionHandler.onSelection(SelectionEvent<Suggestion> event)</code> |
| * method, obtain the selected <code>Suggestion</code> object from the |
| * {@link com.google.gwt.event.logical.shared.SelectionEvent} object, and downcast |
| * the <code>Suggestion</code> object to the subinterface. Then, access 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 |
| */ |
| @IsSafeHtml |
| 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); |
| } |