001: /*
002: * Copyright 2007 Google Inc.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License"); you may not
005: * use this file except in compliance with the License. You may obtain a copy of
006: * the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
012: * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
013: * License for the specific language governing permissions and limitations under
014: * the License.
015: */
016: package com.google.gwt.user.client.ui;
017:
018: import com.google.gwt.user.client.rpc.IsSerializable;
019:
020: import java.util.Collection;
021:
022: /**
023: * A {@link com.google.gwt.user.client.ui.SuggestOracle} can be used to create
024: * suggestions associated with a specific query string. It is currently used by
025: * {@link SuggestBox}.
026: *
027: * @see SuggestBox
028: */
029: public abstract class SuggestOracle {
030:
031: /**
032: * Constructor for {@link com.google.gwt.user.client.ui.SuggestOracle}.
033: */
034: public SuggestOracle() {
035: }
036:
037: /**
038: * Should {@link Suggestion} display strings be treated as HTML? If true, this
039: * all suggestions' display strings will be interpreted as HTML, otherwise as
040: * text.
041: *
042: * @return by default, returns false
043: */
044: public boolean isDisplayStringHTML() {
045: return false;
046: }
047:
048: /**
049: * Generate a {@link Response} based on a specific {@link Request}. After the
050: * {@link Response} is created, it is passed into
051: * {@link Callback#onSuggestionsReady(com.google.gwt.user.client.ui.SuggestOracle.Request, com.google.gwt.user.client.ui.SuggestOracle.Response)}.
052: *
053: * @param request the request
054: * @param callback the callback to use for the response
055: */
056: public abstract void requestSuggestions(Request request,
057: Callback callback);
058:
059: /**
060: * Callback for {@link com.google.gwt.user.client.ui.SuggestOracle}. Every
061: * {@link Request} should be associated with a callback that should be called
062: * after a {@link Response} is generated.
063: */
064: public interface Callback {
065: /**
066: * Consume the suggestions created by a
067: * {@link com.google.gwt.user.client.ui.SuggestOracle} in response to a
068: * {@link Request}.
069: *
070: * @param request the request
071: * @param response the response
072: */
073: public void onSuggestionsReady(Request request,
074: Response response);
075: }
076:
077: /**
078: * A {@link com.google.gwt.user.client.ui.SuggestOracle} request.
079: */
080: public static class Request implements IsSerializable {
081: private int limit = 20;
082: private String query;
083:
084: /**
085: * Constructor for {@link Request}.
086: */
087: public Request() {
088: }
089:
090: /**
091: * Constructor for {@link Request}.
092: *
093: * @param query the query string
094: */
095: public Request(String query) {
096: setQuery(query);
097: }
098:
099: /**
100: * Constructor for {@link Request}.
101: *
102: * @param query the query string
103: * @param limit limit on the number of suggestions that should be created
104: * for this query
105: */
106: public Request(String query, int limit) {
107: setQuery(query);
108: setLimit(limit);
109: }
110:
111: /**
112: * Gets the limit on the number of suggestions that should be created.
113: *
114: * @return the limit
115: */
116: public int getLimit() {
117: return limit;
118: }
119:
120: /**
121: * Gets the query string.
122: *
123: * @return the query string
124: */
125: public String getQuery() {
126: return query;
127: }
128:
129: /**
130: * Sets the limit on the number of suggestions that should be created.
131: *
132: * @param limit the limit
133: */
134: public void setLimit(int limit) {
135: this .limit = limit;
136: }
137:
138: /**
139: * Sets the query string used for this request.
140: *
141: * @param query the query string
142: */
143: public void setQuery(String query) {
144: this .query = query;
145: }
146: }
147:
148: /**
149: * {@link com.google.gwt.user.client.ui.SuggestOracle} response.
150: */
151: public static class Response implements IsSerializable {
152:
153: /**
154: * @gwt.typeArgs <com.google.gwt.user.client.ui.SuggestOracle.Suggestion>
155: */
156: private Collection<? extends Suggestion> suggestions;
157:
158: /**
159: * Constructor for {@link Response}.
160: */
161: public Response() {
162: }
163:
164: /**
165: * Constructor for {@link Response}.
166: *
167: * @param suggestions each element of suggestions must implement the
168: * {@link Suggestion} interface
169: */
170: public Response(Collection<? extends Suggestion> suggestions) {
171: setSuggestions(suggestions);
172: }
173:
174: /**
175: * Gets the collection of suggestions. Each suggestion must implement the
176: * {@link Suggestion} interface.
177: *
178: * @return the collection of suggestions
179: */
180: public Collection<? extends Suggestion> getSuggestions() {
181: return this .suggestions;
182: }
183:
184: /**
185: * Sets the suggestions for this response. Each suggestion must implement
186: * the {@link Suggestion} interface.
187: *
188: * @param suggestions the suggestions
189: */
190: public void setSuggestions(
191: Collection<? extends Suggestion> suggestions) {
192: this .suggestions = suggestions;
193: }
194: }
195:
196: /**
197: * Suggestion supplied by the
198: * {@link com.google.gwt.user.client.ui.SuggestOracle}. Each suggestion has a
199: * display string and a replacement string. The display string is what is
200: * shown in the SuggestBox's list of suggestions. The interpretation of the
201: * display string depends upon the value of its oracle's
202: * {@link SuggestOracle#isDisplayStringHTML()}. The replacement string is
203: * the string that is entered into the SuggestBox's text box when the
204: * suggestion is selected from the list.
205: *
206: * <p>
207: * Replacement strings are useful when the display form of a suggestion
208: * differs from the input format for the data. For example,
209: * suppose that a company has a webpage with a form which requires the user to
210: * enter the e-mail address of an employee. Since users are likely to know
211: * the name of the employee, a SuggestBox is used to provide name suggestions
212: * as the user types. When the user types the letter <i>f</i>, a suggestion
213: * with the display string <i>foo bar</i> appears. When the user chooses this
214: * suggestion, the replacement string, <i>foobar@company.com</i>, is
215: * entered into the SuggestBox's text box.
216: * </p>
217: *
218: * <p>
219: * This is an example where the input data format for the suggestion is not
220: * as user-friendly as the display format. In the event that the display
221: * of a suggestion exactly matches the input data format, the
222: * <code>Suggestion</code> interface would be implemented in such a way
223: * that the display string and replacement string would be identical.
224: * </p>
225: *
226: * <h3>Associating Data Transfer Objects (DTOs) with Suggestion Objects</h3>
227: * Some applications retrieve suggesstions from a server, and may want to send
228: * back a DTO with each suggestion. In the previous example, a DTO returned
229: * with the suggestion may provide additional contact information about the
230: * selected employee, and this information could be used to fill out other
231: * fields on the form. To send back a DTO with each suggestion, extend the
232: * <code>Suggestion</code> interface and define a getter method that has
233: * a return value of the DTO's type. Define a class that implements this
234: * subinterface and use it to encapsulate each suggestion.
235: *
236: * <p>
237: * To access a suggestion's DTO when the suggestion is selected, add a
238: * {@link SuggestionHandler} to the SuggestBox (see SuggestBox's documentation
239: * for more information). In the
240: * <code>SuggestionHandler.onSuggestionSelected(SuggestionEvent event)</code>
241: * method, obtain the selected <code>Suggestion</code> object from the
242: * {@link SuggestionEvent} object, and downcast the <code>Suggestion</code>
243: * object to the subinterface. Then, acces the DTO using the DTO getter method
244: * that was defined on the subinterface.
245: * </p>
246: */
247: public interface Suggestion {
248: /**
249: * Gets the display string associated with this suggestion. The
250: * interpretation of the display string depends upon the value of
251: * its oracle's {@link SuggestOracle#isDisplayStringHTML()}.
252: *
253: * @return the display string for this suggestion
254: */
255: String getDisplayString();
256:
257: /**
258: * Gets the replacement string associated with this suggestion. When
259: * this suggestion is selected, the replacement string will be entered
260: * into the SuggestBox's text box.
261: *
262: * @return the string to be entered into the SuggestBox's text box when
263: * this suggestion is selected
264: */
265: String getReplacementString();
266: }
267: }
|