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}