001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.wicket.extensions.ajax.markup.html.autocomplete;
018
019import org.apache.wicket.util.io.IClusterable;
020
021/**
022 * This class encapsulates various settings for {@link AbstractAutoCompleteBehavior}. See the
023 * documentation for the property accessors of this class for further information.
024 * <p>
025 * Default settings:
026 * <table>
027 * <caption>Default settings</caption>
028 * <tr>
029 * <th>setting</th>
030 * <th>default value</th>
031 * </tr>
032 * <tr>
033 * <td>preselect</td>
034 * <td>false</td>
035 * </tr>
036 * <tr>
037 * <td>maxHeightInPx</td>
038 * <td>-1</td>
039 * </tr>
040 * <tr>
041 * <td>showListOnEmptyInput</td>
042 * <td>false</td>
043 * </tr>
044 * </table>
045 * </p>
046 * 
047 * @author Gerolf Seitz
048 */
049public final class AutoCompleteSettings implements IClusterable
050{
051        private static final long serialVersionUID = 1L;
052
053        private boolean preselect = false;
054
055        private int maxHeightInPx = -1;
056
057        private boolean showListOnEmptyInput = false;
058
059        private boolean useSmartPositioning = false;
060
061        private boolean ignoreBordersWhenPositioning = true;
062
063        private String cssClassName = null;
064
065        private boolean adjustInputWidth = true;
066
067        private boolean showListOnFocusGain = false;
068
069        private boolean showCompleteListOnFocusGain = false;
070
071        private int throttleDelay = 300;
072
073        private String parameterName = "q";
074
075        private int minInputLength = 1;
076
077        /**
078         * Indicates whether the first item in the list is automatically selected when the autocomplete
079         * list is shown.
080         * 
081         * @return true if the first item of the autocomplete list should be preselected, false
082         *         (default) otherwise
083         */
084        public boolean getPreselect()
085        {
086                return preselect;
087        }
088
089        /**
090         * Sets whether the first item in the autocomplete list should be selected when the autocomplete
091         * list is shown.
092         * 
093         * @param preselect
094         *            the flag
095         * @return this {@link AutoCompleteSettings}
096         */
097        public AutoCompleteSettings setPreselect(final boolean preselect)
098        {
099                this.preselect = preselect;
100                return this;
101        }
102
103        /**
104         * set the throttle delay how long the browser will wait before sending a request to the browser
105         * after the user released a key.
106         * 
107         * @param throttleDelay
108         *            The delay in milliseconds.
109         * @return this {@link AutoCompleteSettings}
110         */
111        public AutoCompleteSettings setThrottleDelay(final int throttleDelay)
112        {
113                this.throttleDelay = throttleDelay;
114                return this;
115        }
116
117        /**
118         * get the throttle delay how long the browser will wait before sending a request to the browser
119         * after the user released a key.
120         * 
121         * @return the throttle delay in milliseconds (default 300)
122         */
123        public int getThrottleDelay()
124        {
125                return throttleDelay;
126        }
127
128        /**
129         * Gets the maximum height of the autocomplete list in pixels. <code>-1</code> indicates that
130         * the autocomplete list should have no maximum height.
131         * 
132         * @return the maximum height in pixels
133         */
134        public int getMaxHeightInPx()
135        {
136                return maxHeightInPx;
137        }
138
139        /**
140         * Sets the maximum height in pixels of the autocomplete list.
141         * <p>
142         * The maximum height can also be specified via css (and by setting maxHeightInPx to -1):
143         * 
144         * <pre>
145         * div.wicket-aa-container { maxHeight: 100px; }
146         * </pre>
147         * 
148         * Note that this does not work in IE6.
149         * </p>
150         * 
151         * @param maxHeightInPx
152         *            the maximum height in pixels
153         * @return this {@link AutoCompleteSettings}
154         */
155        public AutoCompleteSettings setMaxHeightInPx(final int maxHeightInPx)
156        {
157                this.maxHeightInPx = maxHeightInPx;
158                return this;
159        }
160
161        /**
162         * Indicates whether the popup positioning will take into account the borders of the input
163         * element and its ancestors.
164         * 
165         * @return true if borders are ignored, false otherwise.
166         */
167        public boolean getIgnoreBordersWhenPositioning()
168        {
169                return ignoreBordersWhenPositioning;
170        }
171
172        /**
173         * Sets whether the popup positioning will take into account the borders of the input element
174         * and its ancestors (by including the <code>clientLeft</code> and <code>clientTop</code> DOM
175         * properties in the computation).
176         * 
177         * @param ignoreBordersWhenPositioning
178         *            the flag
179         * @return this {@link AutoCompleteSettings}.
180         */
181        public AutoCompleteSettings setIgnoreBordersWhenPositioning(
182                final boolean ignoreBordersWhenPositioning)
183        {
184                this.ignoreBordersWhenPositioning = ignoreBordersWhenPositioning;
185                return this;
186        }
187
188        /**
189         * Indicates whether the popup positioning will take into account browser window visible area or
190         * not. (so always show popup bottom-right or not)
191         * 
192         * @return true if popup smart positioning is used, false otherwise.
193         */
194        public boolean getUseSmartPositioning()
195        {
196                return useSmartPositioning;
197        }
198
199        /**
200         * Indicates whether the autocomplete list will be shown if the input is empty.
201         * 
202         * @return true if the autocomlete list will be shown if the input string is empty, false
203         *         otherwise
204         */
205        public boolean getShowListOnEmptyInput()
206        {
207                return showListOnEmptyInput;
208        }
209
210        /**
211         * Sets whether the list should be shown when the input is empty.
212         * 
213         * @param showListOnEmptyInput
214         *            the flag
215         * @return this {@link AutoCompleteSettings}
216         */
217        public AutoCompleteSettings setShowListOnEmptyInput(final boolean showListOnEmptyInput)
218        {
219                this.showListOnEmptyInput = showListOnEmptyInput;
220                return this;
221        }
222
223        /**
224         * Get CSS class name to add to the autocompleter markup container
225         * 
226         * @return CSS class name, or <code>null</code> if not used
227         */
228        public String getCssClassName()
229        {
230                return cssClassName;
231        }
232
233        /**
234         * Sets an CSS class name to add to the autocompleter markup container
235         * <p/>
236         * This makes it easier to have multiple autocompleters in your application with different style
237         * and layout.
238         * 
239         * @param cssClassName
240         *            valid CSS class name
241         * @return this {@link AutoCompleteSettings}.
242         */
243        public AutoCompleteSettings setCssClassName(final String cssClassName)
244        {
245                this.cssClassName = cssClassName;
246                return this;
247        }
248
249        /**
250         * Tells if wicket should adjust the width of the autocompleter selection window to the width of
251         * the related input field.
252         * 
253         * @return <code>true</code> if the autocompleter should have the same size as the input field,
254         *         <code>false</code> for default browser behavior
255         */
256        public boolean isAdjustInputWidth()
257        {
258                return adjustInputWidth;
259        }
260
261        /**
262         * Adjust the width of the autocompleter selection window to the width of the related input
263         * field.
264         * <p/>
265         * Otherwise the size will depend on the default browser behavior and CSS.
266         * 
267         * @param adjustInputWidth
268         *            <code>true</code> if the autocompleter should have the same size as the input
269         *            field, <code>false</code> for default browser behavior
270         * @return this {@link AutoCompleteSettings}.
271         */
272        public AutoCompleteSettings setAdjustInputWidth(final boolean adjustInputWidth)
273        {
274                this.adjustInputWidth = adjustInputWidth;
275                return this;
276        }
277
278        /**
279         * Indicates whether the autocomplete list will be shown when the input field receives focus.
280         * 
281         * @return true if the autocomplete list will be shown when the input field receives focus,
282         *         false otherwise
283         */
284        public boolean getShowListOnFocusGain()
285        {
286                return showListOnFocusGain;
287        }
288
289        /**
290         * Sets whether the list should be shown when the input field receives focus.
291         * 
292         * @param showCompleteListOnFocusGain
293         *            the flag
294         * @return this {@link AutoCompleteSettings}.
295         */
296        public AutoCompleteSettings setShowCompleteListOnFocusGain(
297                final boolean showCompleteListOnFocusGain)
298        {
299                this.showCompleteListOnFocusGain = showCompleteListOnFocusGain;
300                return this;
301        }
302
303        /**
304         * Indicates whether the autocomplete list will be shown when the input field receives focus.
305         * 
306         * @return true if the autocomplete list will be shown when the input field receives focus,
307         *         false otherwise
308         */
309        public boolean getShowCompleteListOnFocusGain()
310        {
311                return showCompleteListOnFocusGain;
312        }
313
314        /**
315         * Sets whether the list should be shown when the input field receives focus.
316         * 
317         * @param showListOnFocusGain
318         *            the flag
319         * @return this {@link AutoCompleteSettings}.
320         */
321        public AutoCompleteSettings setShowListOnFocusGain(final boolean showListOnFocusGain)
322        {
323                this.showListOnFocusGain = showListOnFocusGain;
324                return this;
325        }
326
327        /**
328         * Sets whether the popup positioning will take into account browser window visible area or not.
329         * (so always show popup bottom-right or not)<br>
330         *
331         * @param useSmartPositioning
332         *            the flag
333         * @return this {@link AutoCompleteSettings}.
334         */
335        public AutoCompleteSettings setUseSmartPositioning(final boolean useSmartPositioning)
336        {
337                this.useSmartPositioning = useSmartPositioning;
338                return this;
339        }
340
341        /**
342         * Sets the name of the request parameter that will bring the value of the user input
343         * 
344         * @param parameterName
345         *            the name of the request parameter that will bring the value of the user input
346         * @return this {@link AutoCompleteSettings}
347         */
348        public AutoCompleteSettings setParameterName(final String parameterName)
349        {
350                this.parameterName = parameterName;
351                return this;
352        }
353
354        /**
355         * @return the name of the request parameter that will bring the value of the user input
356         */
357        public String getParameterName()
358        {
359                return parameterName;
360        }
361
362        /**
363         * @return the minimum input length required to display the autocomplete list
364         */
365        public int getMinInputLength()
366        {
367                return minInputLength;
368        }
369
370        /**
371         * Set the minimum input length required to display the autocomplete list
372         *
373         * @param minInputLength
374         *            the minimum input length required to display the autocomplete list
375         * @return this {@link AutoCompleteSettings}
376         */
377        public AutoCompleteSettings setMinInputLength(int minInputLength)
378        {
379                this.minInputLength = minInputLength;
380                return this;
381        }
382}