SuggestOracle


1   /*
2    * Copyright 2007 Google Inc.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License"); you may not
5    * use this file except in compliance with the License. You may obtain a copy of
6    * the License at
7    * 
8    * http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13   * License for the specific language governing permissions and limitations under
14   * the License.
15   */
16  package com.google.gwt.user.client.ui;
17  
18  import com.google.gwt.user.client.rpc.IsSerializable;
19  
20  import java.util.Collection  ;
21  
22  /**
23   * A {@link com.google.gwt.user.client.ui.SuggestOracle} can be used to create
24   * suggestions associated with a specific query string. It is currently used by
25   * {@link SuggestBox}.
26   * 
27   * @see SuggestBox
28   */
29  public abstract class SuggestOracle {
30  
31    /**
32     * Constructor for {@link com.google.gwt.user.client.ui.SuggestOracle}.
33     */
34    public SuggestOracle() {
35    }
36  
37    /**
38     * Should {@link Suggestion} display strings be treated as HTML? If true, this
39     * all suggestions' display strings will be interpreted as HTML, otherwise as
40     * text.
41     * 
42     * @return by default, returns false
43     */
44    public boolean isDisplayStringHTML() {
45      return false;
46    }
47  
48    /**
49     * Generate a {@link Response} based on a specific {@link Request}. After the
50     * {@link Response} is created, it is passed into
51     * {@link Callback#onSuggestionsReady(com.google.gwt.user.client.ui.SuggestOracle.Request, com.google.gwt.user.client.ui.SuggestOracle.Response)}.
52     * 
53     * @param request the request
54     * @param callback the callback to use for the response
55     */
56    public abstract void requestSuggestions(Request request, Callback callback);
57  
58    /**
59     * Callback for {@link com.google.gwt.user.client.ui.SuggestOracle}. Every
60     * {@link Request} should be associated with a callback that should be called
61     * after a {@link  Response} is generated.
62     */
63    public interface Callback {
64      /**
65       * Consume the suggestions created by a
66       * {@link com.google.gwt.user.client.ui.SuggestOracle} in response to a
67       * {@link Request}.
68       * 
69       * @param request the request
70       * @param response the response
71       */
72      public void onSuggestionsReady(Request request, Response response);
73    }
74  
75    /**
76     * A {@link com.google.gwt.user.client.ui.SuggestOracle} request.
77     */
78    public static class Request implements IsSerializable {
79      private int limit = 20;
80      private String   query;
81  
82      /**
83       * Constructor for {@link Request}.
84       */
85      public Request() {
86      }
87  
88      /**
89       * Constructor for {@link Request}.
90       * 
91       * @param query the query string
92       */
93      public Request(String   query) {
94        setQuery(query);
95      }
96  
97      /**
98       * Constructor for {@link Request}.
99       * 
100      * @param query the query string
101      * @param limit limit on the number of suggestions that should be created
102      *          for this query
103      */
104     public Request(String   query, int limit) {
105       setQuery(query);
106       setLimit(limit);
107     }
108 
109     /**
110      * Gets the limit on the number of suggestions that should be created.
111      * 
112      * @return the limit
113      */
114     public int getLimit() {
115       return limit;
116     }
117 
118     /**
119      * Gets the query string.
120      * 
121      * @return the query string
122      */
123     public String   getQuery() {
124       return query;
125     }
126 
127     /**
128      * Sets the limit on the number of suggestions that should be created.
129      * 
130      * @param limit the limit
131      */
132     public void setLimit(int limit) {
133       this.limit = limit;
134     }
135 
136     /**
137      * Sets the query string used for this request.
138      * 
139      * @param query the query string
140      */
141     public void setQuery(String   query) {
142       this.query = query;
143     }
144   }
145 
146   /**
147    * {@link com.google.gwt.user.client.ui.SuggestOracle} response.
148    */
149   public static class Response implements IsSerializable {
150 
151     /**
152      * @gwt.typeArgs <com.google.gwt.user.client.ui.SuggestOracle.Suggestion>
153      */
154     private Collection   suggestions;
155 
156     /**
157      * Constructor for {@link Response}.
158      */
159     public Response() {
160     }
161 
162     /**
163      * Constructor for {@link Response}.
164      * 
165      * @param suggestions each element of suggestions must implement the
166      *          {@link Suggestion} interface
167      */
168     public Response(Collection   suggestions) {
169       setSuggestions(suggestions);
170     }
171 
172     /**
173      * Gets the collection of suggestions. Each suggestion must implement the
174      * {@link Suggestion} interface.
175      * 
176      * @return the collection of suggestions
177      */
178     public Collection   getSuggestions() {
179       return this.suggestions;
180     }
181 
182     /**
183      * Sets the suggestions for this response. Each suggestion must implement
184      * the {@link Suggestion} interface.
185      * 
186      * @param suggestions the suggestions
187      */
188     public void setSuggestions(Collection   suggestions) {
189       this.suggestions = suggestions;
190     }
191   }
192 
193   /**
194    * Suggestion supplied by the
195    * {@link com.google.gwt.user.client.ui.SuggestOracle}. Each suggestion has a
196    * value and a display string. The interpretation of the display string
197    * depends upon the value of its oracle's {@link SuggestOracle#isDisplayStringHTML()}.
198    * 
199    */
200   public interface Suggestion {
201     /**
202      * Gets the display string associated with this suggestion. The
203      * interpretation of the display string depends upon the value of
204      * its oracle's {@link SuggestOracle#isDisplayStringHTML()}.
205      * 
206      * @return the display string
207      */
208     String   getDisplayString();
209 
210     /**
211      * Get the value associated with this suggestion.
212      * 
213      * @return the value
214      */
215     Object   getValue();
216   }
217 }
218
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags