docs/source/ComboBox.html

   1 <!DOCTYPE html>
   2 <html>
   3 <head>
   4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   5   <title>The source code</title>
   6   <link href="../prettify/prettify.css" type="text/css" rel="stylesheet" />
   7   <script type="text/javascript" src="../prettify/prettify.js"></script>
   8   <style type="text/css">
   9     .highlight { display: block; background-color: #ddd; }
  10   </style>
  11   <script type="text/javascript">
  12     function highlight() {
  13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
  14     }
  15   </script>
  16 </head>
  17 <body onload="prettyPrint(); highlight();">
  18   <pre class="prettyprint lang-js"><span id='Ext-form-field-ComboBox-method-constructor'><span id='Ext-form-field-ComboBox'>/**
  19 </span></span> * @class Ext.form.field.ComboBox
  20  * @extends Ext.form.field.Picker
  21  *
  22  * A combobox control with support for autocomplete, remote loading, and many other features.
  23  *
  24  * A ComboBox is like a combination of a traditional HTML text `&lt;input&gt;` field and a `&lt;select&gt;`
  25  * field; the user is able to type freely into the field, and/or pick values from a dropdown selection
  26  * list. The user can input any value by default, even if it does not appear in the selection list;
  27  * to prevent free-form values and restrict them to items in the list, set {@link #forceSelection} to `true`.
  28  *
  29  * The selection list's options are populated from any {@link Ext.data.Store}, including remote
  30  * stores. The data items in the store are mapped to each option's displayed text and backing value via
  31  * the {@link #valueField} and {@link #displayField} configurations, respectively.
  32  *
  33  * If your store is not remote, i.e. it depends only on local data and is loaded up front, you should be
  34  * sure to set the {@link #queryMode} to `'local'`, as this will improve responsiveness for the user.
  35  *
  36  * {@img Ext.form.ComboBox/Ext.form.ComboBox.png Ext.form.ComboBox component}
  37  *
  38  * ## Example usage:
  39  *
  40  *     // The data store containing the list of states
  41  *     var states = Ext.create('Ext.data.Store', {
  42  *         fields: ['abbr', 'name'],
  43  *         data : [
  44  *             {&quot;abbr&quot;:&quot;AL&quot;, &quot;name&quot;:&quot;Alabama&quot;},
  45  *             {&quot;abbr&quot;:&quot;AK&quot;, &quot;name&quot;:&quot;Alaska&quot;},
  46  *             {&quot;abbr&quot;:&quot;AZ&quot;, &quot;name&quot;:&quot;Arizona&quot;}
  47  *             //...
  48  *         ]
  49  *     });
  50  *
  51  *     // Create the combo box, attached to the states data store
  52  *     Ext.create('Ext.form.ComboBox', {
  53  *         fieldLabel: 'Choose State',
  54  *         store: states,
  55  *         queryMode: 'local',
  56  *         displayField: 'name',
  57  *         valueField: 'abbr',
  58  *         renderTo: Ext.getBody()
  59  *     });
  60  *
  61  * ## Events
  62  *
  63  * To do something when something in ComboBox is selected, configure the select event:
  64  *
  65  *     var cb = Ext.create('Ext.form.ComboBox', {
  66  *         // all of your config options
  67  *         listeners:{
  68  *              scope: yourScope,
  69  *              'select': yourFunction
  70  *         }
  71  *     });
  72  *
  73  *     // Alternatively, you can assign events after the object is created:
  74  *     var cb = new Ext.form.field.ComboBox(yourOptions);
  75  *     cb.on('select', yourFunction, yourScope);
  76  *
  77  * ## Multiple Selection
  78  *
  79  * ComboBox also allows selection of multiple items from the list; to enable multi-selection set the
  80  * {@link #multiSelect} config to `true`.
  81  *
  82  * @constructor
  83  * Create a new ComboBox.
  84  * @param {Object} config Configuration options
  85  * @xtype combo
  86  * @docauthor Jason Johnston &lt;jason@sencha.com&gt;
  87  */
  88 Ext.define('Ext.form.field.ComboBox', {
  89     extend:'Ext.form.field.Picker',
  90     requires: ['Ext.util.DelayedTask', 'Ext.EventObject', 'Ext.view.BoundList', 'Ext.view.BoundListKeyNav', 'Ext.data.StoreManager'],
  91     alternateClassName: 'Ext.form.ComboBox',
  92     alias: ['widget.combobox', 'widget.combo'],
  93
  94 <span id='Ext-form-field-ComboBox-cfg-triggerCls'>    /**
  95 </span>     * @cfg {String} triggerCls
  96      * An additional CSS class used to style the trigger button. The trigger will always get the
  97      * {@link #triggerBaseCls} by default and &lt;tt&gt;triggerCls&lt;/tt&gt; will be &lt;b&gt;appended&lt;/b&gt; if specified.
  98      * Defaults to 'x-form-arrow-trigger' for ComboBox.
  99      */
 100     triggerCls: Ext.baseCSSPrefix + 'form-arrow-trigger',
 101
 102 <span id='Ext-form-field-ComboBox-cfg-store'>    /**
 103 </span>     * @cfg {Ext.data.Store/Array} store The data source to which this combo is bound (defaults to &lt;tt&gt;undefined&lt;/tt&gt;).
 104      * Acceptable values for this property are:
 105      * &lt;div class=&quot;mdetail-params&quot;&gt;&lt;ul&gt;
 106      * &lt;li&gt;&lt;b&gt;any {@link Ext.data.Store Store} subclass&lt;/b&gt;&lt;/li&gt;
 107      * &lt;li&gt;&lt;b&gt;an Array&lt;/b&gt; : Arrays will be converted to a {@link Ext.data.Store} internally,
 108      * automatically generating {@link Ext.data.Field#name field names} to work with all data components.
 109      * &lt;div class=&quot;mdetail-params&quot;&gt;&lt;ul&gt;
 110      * &lt;li&gt;&lt;b&gt;1-dimensional array&lt;/b&gt; : (e.g., &lt;tt&gt;['Foo','Bar']&lt;/tt&gt;)&lt;div class=&quot;sub-desc&quot;&gt;
 111      * A 1-dimensional array will automatically be expanded (each array item will be used for both the combo
 112      * {@link #valueField} and {@link #displayField})&lt;/div&gt;&lt;/li&gt;
 113      * &lt;li&gt;&lt;b&gt;2-dimensional array&lt;/b&gt; : (e.g., &lt;tt&gt;[['f','Foo'],['b','Bar']]&lt;/tt&gt;)&lt;div class=&quot;sub-desc&quot;&gt;
 114      * For a multi-dimensional array, the value in index 0 of each item will be assumed to be the combo
 115      * {@link #valueField}, while the value at index 1 is assumed to be the combo {@link #displayField}.
 116      * &lt;/div&gt;&lt;/li&gt;&lt;/ul&gt;&lt;/div&gt;&lt;/li&gt;&lt;/ul&gt;&lt;/div&gt;
 117      * &lt;p&gt;See also &lt;tt&gt;{@link #queryMode}&lt;/tt&gt;.&lt;/p&gt;
 118      */
 119
 120 <span id='Ext-form-field-ComboBox-cfg-multiSelect'>    /**
 121 </span>     * @cfg {Boolean} multiSelect
 122      * If set to &lt;tt&gt;true&lt;/tt&gt;, allows the combo field to hold more than one value at a time, and allows selecting
 123      * multiple items from the dropdown list. The combo's text field will show all selected values separated by
 124      * the {@link #delimiter}. (Defaults to &lt;tt&gt;false&lt;/tt&gt;.)
 125      */
 126     multiSelect: false,
 127
 128 <span id='Ext-form-field-ComboBox-cfg-delimiter'>    /**
 129 </span>     * @cfg {String} delimiter
 130      * The character(s) used to separate the {@link #displayField display values} of multiple selected items
 131      * when &lt;tt&gt;{@link #multiSelect} = true&lt;/tt&gt;. Defaults to &lt;tt&gt;', '&lt;/tt&gt;.
 132      */
 133     delimiter: ', ',
 134
 135 <span id='Ext-form-field-ComboBox-cfg-displayField'>    /**
 136 </span>     * @cfg {String} displayField The underlying {@link Ext.data.Field#name data field name} to bind to this
 137      * ComboBox (defaults to 'text').
 138      * &lt;p&gt;See also &lt;tt&gt;{@link #valueField}&lt;/tt&gt;.&lt;/p&gt;
 139      */
 140     displayField: 'text',
 141
 142 <span id='Ext-form-field-ComboBox-cfg-valueField'>    /**
 143 </span>     * @cfg {String} valueField
 144      * @required
 145      * The underlying {@link Ext.data.Field#name data value name} to bind to this ComboBox (defaults to match
 146      * the value of the {@link #displayField} config).
 147      * &lt;p&gt;&lt;b&gt;Note&lt;/b&gt;: use of a &lt;tt&gt;valueField&lt;/tt&gt; requires the user to make a selection in order for a value to be
 148      * mapped. See also &lt;tt&gt;{@link #displayField}&lt;/tt&gt;.&lt;/p&gt;
 149      */
 150
 151 <span id='Ext-form-field-ComboBox-cfg-triggerAction'>    /**
 152 </span>     * @cfg {String} triggerAction The action to execute when the trigger is clicked.
 153      * &lt;div class=&quot;mdetail-params&quot;&gt;&lt;ul&gt;
 154      * &lt;li&gt;&lt;b&gt;&lt;tt&gt;'all'&lt;/tt&gt;&lt;/b&gt; : &lt;b&gt;Default&lt;/b&gt;
 155      * &lt;p class=&quot;sub-desc&quot;&gt;{@link #doQuery run the query} specified by the &lt;tt&gt;{@link #allQuery}&lt;/tt&gt; config option&lt;/p&gt;&lt;/li&gt;
 156      * &lt;li&gt;&lt;b&gt;&lt;tt&gt;'query'&lt;/tt&gt;&lt;/b&gt; :
 157      * &lt;p class=&quot;sub-desc&quot;&gt;{@link #doQuery run the query} using the {@link Ext.form.field.Base#getRawValue raw value}.&lt;/p&gt;&lt;/li&gt;
 158      * &lt;/ul&gt;&lt;/div&gt;
 159      * &lt;p&gt;See also &lt;code&gt;{@link #queryParam}&lt;/code&gt;.&lt;/p&gt;
 160      */
 161     triggerAction: 'all',
 162
 163 <span id='Ext-form-field-ComboBox-cfg-allQuery'>    /**
 164 </span>     * @cfg {String} allQuery The text query to send to the server to return all records for the list
 165      * with no filtering (defaults to '')
 166      */
 167     allQuery: '',
 168
 169 <span id='Ext-form-field-ComboBox-cfg-queryParam'>    /**
 170 </span>     * @cfg {String} queryParam Name of the query ({@link Ext.data.proxy.Proxy#extraParam extraParam} name for the store)
 171      * as it will be passed on the querystring (defaults to &lt;tt&gt;'query'&lt;/tt&gt;). If explicitly set to a falsey value it will
 172      * not be send.
 173      */
 174     queryParam: 'query',
 175
 176 <span id='Ext-form-field-ComboBox-cfg-queryMode'>    /**
 177 </span>     * @cfg {String} queryMode
 178      * The mode for queries. Acceptable values are:
 179      * &lt;div class=&quot;mdetail-params&quot;&gt;&lt;ul&gt;
 180      * &lt;li&gt;&lt;b&gt;&lt;tt&gt;'remote'&lt;/tt&gt;&lt;/b&gt; : &lt;b&gt;Default&lt;/b&gt;
 181      * &lt;p class=&quot;sub-desc&quot;&gt;Automatically loads the &lt;tt&gt;{@link #store}&lt;/tt&gt; the &lt;b&gt;first&lt;/b&gt; time the trigger
 182      * is clicked. If you do not want the store to be automatically loaded the first time the trigger is
 183      * clicked, set to &lt;tt&gt;'local'&lt;/tt&gt; and manually load the store.  To force a requery of the store
 184      * &lt;b&gt;every&lt;/b&gt; time the trigger is clicked see &lt;tt&gt;{@link #lastQuery}&lt;/tt&gt;.&lt;/p&gt;&lt;/li&gt;
 185      * &lt;li&gt;&lt;b&gt;&lt;tt&gt;'local'&lt;/tt&gt;&lt;/b&gt; :
 186      * &lt;p class=&quot;sub-desc&quot;&gt;ComboBox loads local data&lt;/p&gt;
 187      * &lt;pre&gt;&lt;code&gt;
 188 var combo = new Ext.form.field.ComboBox({
 189     renderTo: document.body,
 190     queryMode: 'local',
 191     store: new Ext.data.ArrayStore({
 192         id: 0,
 193         fields: [
 194             'myId',  // numeric value is the key
 195             'displayText'
 196         ],
 197         data: [[1, 'item1'], [2, 'item2']]  // data is local
 198     }),
 199     valueField: 'myId',
 200     displayField: 'displayText',
 201     triggerAction: 'all'
 202 });
 203      * &lt;/code&gt;&lt;/pre&gt;&lt;/li&gt;
 204      * &lt;/ul&gt;&lt;/div&gt;
 205      */
 206     queryMode: 'remote',
 207
 208     queryCaching: true,
 209
 210 <span id='Ext-form-field-ComboBox-cfg-pageSize'>    /**
 211 </span>     * @cfg {Number} pageSize If greater than &lt;tt&gt;0&lt;/tt&gt;, a {@link Ext.toolbar.Paging} is displayed in the
 212      * footer of the dropdown list and the {@link #doQuery filter queries} will execute with page start and
 213      * {@link Ext.toolbar.Paging#pageSize limit} parameters. Only applies when &lt;tt&gt;{@link #queryMode} = 'remote'&lt;/tt&gt;
 214      * (defaults to &lt;tt&gt;0&lt;/tt&gt;).
 215      */
 216     pageSize: 0,
 217
 218 <span id='Ext-form-field-ComboBox-cfg-queryDelay'>    /**
 219 </span>     * @cfg {Number} queryDelay The length of time in milliseconds to delay between the start of typing and
 220      * sending the query to filter the dropdown list (defaults to &lt;tt&gt;500&lt;/tt&gt; if &lt;tt&gt;{@link #queryMode} = 'remote'&lt;/tt&gt;
 221      * or &lt;tt&gt;10&lt;/tt&gt; if &lt;tt&gt;{@link #queryMode} = 'local'&lt;/tt&gt;)
 222      */
 223
 224 <span id='Ext-form-field-ComboBox-cfg-minChars'>    /**
 225 </span>     * @cfg {Number} minChars The minimum number of characters the user must type before autocomplete and
 226      * {@link #typeAhead} activate (defaults to &lt;tt&gt;4&lt;/tt&gt; if &lt;tt&gt;{@link #queryMode} = 'remote'&lt;/tt&gt; or &lt;tt&gt;0&lt;/tt&gt; if
 227      * &lt;tt&gt;{@link #queryMode} = 'local'&lt;/tt&gt;, does not apply if &lt;tt&gt;{@link Ext.form.field.Trigger#editable editable} = false&lt;/tt&gt;).
 228      */
 229
 230 <span id='Ext-form-field-ComboBox-cfg-autoSelect'>    /**
 231 </span>     * @cfg {Boolean} autoSelect &lt;tt&gt;true&lt;/tt&gt; to automatically highlight the first result gathered by the data store
 232      * in the dropdown list when it is opened. (Defaults to &lt;tt&gt;true&lt;/tt&gt;). A false value would cause nothing in the
 233      * list to be highlighted automatically, so the user would have to manually highlight an item before pressing
 234      * the enter or {@link #selectOnTab tab} key to select it (unless the value of ({@link #typeAhead}) were true),
 235      * or use the mouse to select a value.
 236      */
 237     autoSelect: true,
 238
 239 <span id='Ext-form-field-ComboBox-cfg-typeAhead'>    /**
 240 </span>     * @cfg {Boolean} typeAhead &lt;tt&gt;true&lt;/tt&gt; to populate and autoselect the remainder of the text being
 241      * typed after a configurable delay ({@link #typeAheadDelay}) if it matches a known value (defaults
 242      * to &lt;tt&gt;false&lt;/tt&gt;)
 243      */
 244     typeAhead: false,
 245
 246 <span id='Ext-form-field-ComboBox-cfg-typeAheadDelay'>    /**
 247 </span>     * @cfg {Number} typeAheadDelay The length of time in milliseconds to wait until the typeahead text is displayed
 248      * if &lt;tt&gt;{@link #typeAhead} = true&lt;/tt&gt; (defaults to &lt;tt&gt;250&lt;/tt&gt;)
 249      */
 250     typeAheadDelay: 250,
 251
 252 <span id='Ext-form-field-ComboBox-cfg-selectOnTab'>    /**
 253 </span>     * @cfg {Boolean} selectOnTab
 254      * Whether the Tab key should select the currently highlighted item. Defaults to &lt;tt&gt;true&lt;/tt&gt;.
 255      */
 256     selectOnTab: true,
 257
 258 <span id='Ext-form-field-ComboBox-cfg-forceSelection'>    /**
 259 </span>     * @cfg {Boolean} forceSelection &lt;tt&gt;true&lt;/tt&gt; to restrict the selected value to one of the values in the list,
 260      * &lt;tt&gt;false&lt;/tt&gt; to allow the user to set arbitrary text into the field (defaults to &lt;tt&gt;false&lt;/tt&gt;)
 261      */
 262     forceSelection: false,
 263
 264 <span id='Ext-form-field-ComboBox-cfg-valueNotFoundText'>    /**
 265 </span>     * @cfg {String} valueNotFoundText When using a name/value combo, if the value passed to setValue is not found in
 266      * the store, valueNotFoundText will be displayed as the field text if defined (defaults to undefined). If this
 267      * default text is used, it means there is no value set and no validation will occur on this field.
 268      */
 269
 270 <span id='Ext-form-field-ComboBox-property-lastQuery'>    /**
 271 </span>     * The value of the match string used to filter the store. Delete this property to force a requery.
 272      * Example use:
 273      * &lt;pre&gt;&lt;code&gt;
 274 var combo = new Ext.form.field.ComboBox({
 275     ...
 276     queryMode: 'remote',
 277     listeners: {
 278         // delete the previous query in the beforequery event or set
 279         // combo.lastQuery = null (this will reload the store the next time it expands)
 280         beforequery: function(qe){
 281             delete qe.combo.lastQuery;
 282         }
 283     }
 284 });
 285      * &lt;/code&gt;&lt;/pre&gt;
 286      * To make sure the filter in the store is not cleared the first time the ComboBox trigger is used
 287      * configure the combo with &lt;tt&gt;lastQuery=''&lt;/tt&gt;. Example use:
 288      * &lt;pre&gt;&lt;code&gt;
 289 var combo = new Ext.form.field.ComboBox({
 290     ...
 291     queryMode: 'local',
 292     triggerAction: 'all',
 293     lastQuery: ''
 294 });
 295      * &lt;/code&gt;&lt;/pre&gt;
 296      * @property lastQuery
 297      * @type String
 298      */
 299
 300 <span id='Ext-form-field-ComboBox-cfg-defaultListConfig'>    /**
 301 </span>     * @cfg {Object} defaultListConfig
 302      * Set of options that will be used as defaults for the user-configured {@link #listConfig} object.
 303      */
 304     defaultListConfig: {
 305         emptyText: '',
 306         loadingText: 'Loading...',
 307         loadingHeight: 70,
 308         minWidth: 70,
 309         maxHeight: 300,
 310         shadow: 'sides'
 311     },
 312
 313 <span id='Ext-form-field-ComboBox-cfg-transform'>    /**
 314 </span>     * @cfg {Mixed} transform
 315      * The id, DOM node or {@link Ext.core.Element} of an existing HTML &lt;tt&gt;&amp;lt;select&amp;gt;&lt;/tt&gt; element to
 316      * convert into a ComboBox. The target select's options will be used to build the options in the ComboBox
 317      * dropdown; a configured {@link #store} will take precedence over this.
 318      */
 319
 320 <span id='Ext-form-field-ComboBox-cfg-listConfig'>    /**
 321 </span>     * @cfg {Object} listConfig
 322      * &lt;p&gt;An optional set of configuration properties that will be passed to the {@link Ext.view.BoundList}'s
 323      * constructor. Any configuration that is valid for BoundList can be included. Some of the more useful
 324      * ones are:&lt;/p&gt;
 325      * &lt;ul&gt;
 326      *     &lt;li&gt;{@link Ext.view.BoundList#cls} - defaults to empty&lt;/li&gt;
 327      *     &lt;li&gt;{@link Ext.view.BoundList#emptyText} - defaults to empty string&lt;/li&gt;
 328      *     &lt;li&gt;{@link Ext.view.BoundList#getInnerTpl} - defaults to the template defined in BoundList&lt;/li&gt;
 329      *     &lt;li&gt;{@link Ext.view.BoundList#itemSelector} - defaults to the value defined in BoundList&lt;/li&gt;
 330      *     &lt;li&gt;{@link Ext.view.BoundList#loadingText} - defaults to &lt;tt&gt;'Loading...'&lt;/tt&gt;&lt;/li&gt;
 331      *     &lt;li&gt;{@link Ext.view.BoundList#minWidth} - defaults to &lt;tt&gt;70&lt;/tt&gt;&lt;/li&gt;
 332      *     &lt;li&gt;{@link Ext.view.BoundList#maxWidth} - defaults to &lt;tt&gt;undefined&lt;/tt&gt;&lt;/li&gt;
 333      *     &lt;li&gt;{@link Ext.view.BoundList#maxHeight} - defaults to &lt;tt&gt;300&lt;/tt&gt;&lt;/li&gt;
 334      *     &lt;li&gt;{@link Ext.view.BoundList#resizable} - defaults to &lt;tt&gt;false&lt;/tt&gt;&lt;/li&gt;
 335      *     &lt;li&gt;{@link Ext.view.BoundList#shadow} - defaults to &lt;tt&gt;'sides'&lt;/tt&gt;&lt;/li&gt;
 336      *     &lt;li&gt;{@link Ext.view.BoundList#width} - defaults to &lt;tt&gt;undefined&lt;/tt&gt; (automatically set to the width
 337      *         of the ComboBox field if {@link #matchFieldWidth} is true)&lt;/li&gt;
 338      * &lt;/ul&gt;
 339      */
 340
 341     //private
 342     ignoreSelection: 0,
 343
 344     initComponent: function() {
 345         var me = this,
 346             isDefined = Ext.isDefined,
 347             store = me.store,
 348             transform = me.transform,
 349             transformSelect, isLocalMode;
 350
 351         //&lt;debug&gt;
 352         if (!store &amp;&amp; !transform) {
 353             Ext.Error.raise('Either a valid store, or a HTML select to transform, must be configured on the combo.');
 354         }
 355         if (me.typeAhead &amp;&amp; me.multiSelect) {
 356             Ext.Error.raise('typeAhead and multiSelect are mutually exclusive options -- please remove one of them.');
 357         }
 358         if (me.typeAhead &amp;&amp; !me.editable) {
 359             Ext.Error.raise('If typeAhead is enabled the combo must be editable: true -- please change one of those settings.');
 360         }
 361         if (me.selectOnFocus &amp;&amp; !me.editable) {
 362             Ext.Error.raise('If selectOnFocus is enabled the combo must be editable: true -- please change one of those settings.');
 363         }
 364         //&lt;/debug&gt;
 365
 366         this.addEvents(
 367             // TODO need beforeselect?
 368
 369 <span id='Ext-form-field-ComboBox-event-beforequery'>            /**
 370 </span>             * @event beforequery
 371              * Fires before all queries are processed. Return false to cancel the query or set the queryEvent's
 372              * cancel property to true.
 373              * @param {Object} queryEvent An object that has these properties:&lt;ul&gt;
 374              * &lt;li&gt;&lt;code&gt;combo&lt;/code&gt; : Ext.form.field.ComboBox &lt;div class=&quot;sub-desc&quot;&gt;This combo box&lt;/div&gt;&lt;/li&gt;
 375              * &lt;li&gt;&lt;code&gt;query&lt;/code&gt; : String &lt;div class=&quot;sub-desc&quot;&gt;The query string&lt;/div&gt;&lt;/li&gt;
 376              * &lt;li&gt;&lt;code&gt;forceAll&lt;/code&gt; : Boolean &lt;div class=&quot;sub-desc&quot;&gt;True to force &quot;all&quot; query&lt;/div&gt;&lt;/li&gt;
 377              * &lt;li&gt;&lt;code&gt;cancel&lt;/code&gt; : Boolean &lt;div class=&quot;sub-desc&quot;&gt;Set to true to cancel the query&lt;/div&gt;&lt;/li&gt;
 378              * &lt;/ul&gt;
 379              */
 380             'beforequery',
 381
 382             /*
 383              * @event select
 384              * Fires when at least one list item is selected.
 385              * @param {Ext.form.field.ComboBox} combo This combo box
 386              * @param {Array} records The selected records
 387              */
 388             'select'
 389         );
 390
 391         // Build store from 'transform' HTML select element's options
 392         if (!store &amp;&amp; transform) {
 393             transformSelect = Ext.getDom(transform);
 394             if (transformSelect) {
 395                 store = Ext.Array.map(Ext.Array.from(transformSelect.options), function(option) {
 396                     return [option.value, option.text];
 397                 });
 398                 if (!me.name) {
 399                     me.name = transformSelect.name;
 400                 }
 401                 if (!('value' in me)) {
 402                     me.value = transformSelect.value;
 403                 }
 404             }
 405         }
 406
 407         me.bindStore(store, true);
 408         store = me.store;
 409         if (store.autoCreated) {
 410             me.queryMode = 'local';
 411             me.valueField = me.displayField = 'field1';
 412             if (!store.expanded) {
 413                 me.displayField = 'field2';
 414             }
 415         }
 416
 417
 418         if (!isDefined(me.valueField)) {
 419             me.valueField = me.displayField;
 420         }
 421
 422         isLocalMode = me.queryMode === 'local';
 423         if (!isDefined(me.queryDelay)) {
 424             me.queryDelay = isLocalMode ? 10 : 500;
 425         }
 426         if (!isDefined(me.minChars)) {
 427             me.minChars = isLocalMode ? 0 : 4;
 428         }
 429
 430         if (!me.displayTpl) {
 431             me.displayTpl = Ext.create('Ext.XTemplate',
 432                 '&lt;tpl for=&quot;.&quot;&gt;' +
 433                     '{[typeof values === &quot;string&quot; ? values : values.' + me.displayField + ']}' +
 434                     '&lt;tpl if=&quot;xindex &lt; xcount&quot;&gt;' + me.delimiter + '&lt;/tpl&gt;' +
 435                 '&lt;/tpl&gt;'
 436             );
 437         } else if (Ext.isString(me.displayTpl)) {
 438             me.displayTpl = Ext.create('Ext.XTemplate', me.displayTpl);
 439         }
 440
 441         me.callParent();
 442
 443         me.doQueryTask = Ext.create('Ext.util.DelayedTask', me.doRawQuery, me);
 444
 445         // store has already been loaded, setValue
 446         if (me.store.getCount() &gt; 0) {
 447             me.setValue(me.value);
 448         }
 449
 450         // render in place of 'transform' select
 451         if (transformSelect) {
 452             me.render(transformSelect.parentNode, transformSelect);
 453             Ext.removeNode(transformSelect);
 454             delete me.renderTo;
 455         }
 456     },
 457
 458     beforeBlur: function() {
 459         var me = this;
 460         me.doQueryTask.cancel();
 461         if (me.forceSelection) {
 462             me.assertValue();
 463         } else {
 464             me.collapse();
 465         }
 466     },
 467
 468     // private
 469     assertValue: function() {
 470         var me = this,
 471             value = me.getRawValue(),
 472             rec;
 473
 474         if (me.multiSelect) {
 475             // For multiselect, check that the current displayed value matches the current
 476             // selection, if it does not then revert to the most recent selection.
 477             if (value !== me.getDisplayValue()) {
 478                 me.setValue(me.lastSelection);
 479             }
 480         } else {
 481             // For single-select, match the displayed value to a record and select it,
 482             // if it does not match a record then revert to the most recent selection.
 483             rec = me.findRecordByDisplay(value);
 484             if (rec) {
 485                 me.select(rec);
 486             } else {
 487                 me.setValue(me.lastSelection);
 488             }
 489         }
 490         me.collapse();
 491     },
 492
 493     onTypeAhead: function() {
 494         var me = this,
 495             displayField = me.displayField,
 496             record = me.store.findRecord(displayField, me.getRawValue()),
 497             boundList = me.getPicker(),
 498             newValue, len, selStart;
 499
 500         if (record) {
 501             newValue = record.get(displayField);
 502             len = newValue.length;
 503             selStart = me.getRawValue().length;
 504
 505             boundList.highlightItem(boundList.getNode(record));
 506
 507             if (selStart !== 0 &amp;&amp; selStart !== len) {
 508                 me.setRawValue(newValue);
 509                 me.selectText(selStart, newValue.length);
 510             }
 511         }
 512     },
 513
 514     // invoked when a different store is bound to this combo
 515     // than the original
 516     resetToDefault: function() {
 517
 518     },
 519
 520     bindStore: function(store, initial) {
 521         var me = this,
 522             oldStore = me.store;
 523
 524         // this code directly accesses this.picker, bc invoking getPicker
 525         // would create it when we may be preping to destroy it
 526         if (oldStore &amp;&amp; !initial) {
 527             if (oldStore !== store &amp;&amp; oldStore.autoDestroy) {
 528                 oldStore.destroy();
 529             } else {
 530                 oldStore.un({
 531                     scope: me,
 532                     load: me.onLoad,
 533                     exception: me.collapse
 534                 });
 535             }
 536             if (!store) {
 537                 me.store = null;
 538                 if (me.picker) {
 539                     me.picker.bindStore(null);
 540                 }
 541             }
 542         }
 543         if (store) {
 544             if (!initial) {
 545                 me.resetToDefault();
 546             }
 547
 548             me.store = Ext.data.StoreManager.lookup(store);
 549             me.store.on({
 550                 scope: me,
 551                 load: me.onLoad,
 552                 exception: me.collapse
 553             });
 554
 555             if (me.picker) {
 556                 me.picker.bindStore(store);
 557             }
 558         }
 559     },
 560
 561     onLoad: function() {
 562         var me = this,
 563             value = me.value;
 564
 565         me.syncSelection();
 566         if (me.picker &amp;&amp; !me.picker.getSelectionModel().hasSelection()) {
 567             me.doAutoSelect();
 568         }
 569     },
 570
 571 <span id='Ext-form-field-ComboBox-method-doRawQuery'>    /**
 572 </span>     * @private
 573      * Execute the query with the raw contents within the textfield.
 574      */
 575     doRawQuery: function() {
 576         this.doQuery(this.getRawValue());
 577     },
 578
 579 <span id='Ext-form-field-ComboBox-method-doQuery'>    /**
 580 </span>     * Executes a query to filter the dropdown list. Fires the {@link #beforequery} event prior to performing the
 581      * query allowing the query action to be canceled if needed.
 582      * @param {String} queryString The SQL query to execute
 583      * @param {Boolean} forceAll &lt;tt&gt;true&lt;/tt&gt; to force the query to execute even if there are currently fewer
 584      * characters in the field than the minimum specified by the &lt;tt&gt;{@link #minChars}&lt;/tt&gt; config option.  It
 585      * also clears any filter previously saved in the current store (defaults to &lt;tt&gt;false&lt;/tt&gt;)
 586      * @return {Boolean} true if the query was permitted to run, false if it was cancelled by a {@link #beforequery} handler.
 587      */
 588     doQuery: function(queryString, forceAll) {
 589         queryString = queryString || '';
 590
 591         // store in object and pass by reference in 'beforequery'
 592         // so that client code can modify values.
 593         var me = this,
 594             qe = {
 595                 query: queryString,
 596                 forceAll: forceAll,
 597                 combo: me,
 598                 cancel: false
 599             },
 600             store = me.store,
 601             isLocalMode = me.queryMode === 'local';
 602
 603         if (me.fireEvent('beforequery', qe) === false || qe.cancel) {
 604             return false;
 605         }
 606
 607         // get back out possibly modified values
 608         queryString = qe.query;
 609         forceAll = qe.forceAll;
 610
 611         // query permitted to run
 612         if (forceAll || (queryString.length &gt;= me.minChars)) {
 613             // expand before starting query so LoadMask can position itself correctly
 614             me.expand();
 615
 616             // make sure they aren't querying the same thing
 617             if (!me.queryCaching || me.lastQuery !== queryString) {
 618                 me.lastQuery = queryString;
 619                 store.clearFilter(!forceAll);
 620                 if (isLocalMode) {
 621                     if (!forceAll) {
 622                         store.filter(me.displayField, queryString);
 623                     }
 624                 } else {
 625                     store.load({
 626                         params: me.getParams(queryString)
 627                     });
 628                 }
 629             }
 630
 631             // Clear current selection if it does not match the current value in the field
 632             if (me.getRawValue() !== me.getDisplayValue()) {
 633                 me.ignoreSelection++;
 634                 me.picker.getSelectionModel().deselectAll();
 635                 me.ignoreSelection--;
 636             }
 637
 638             if (isLocalMode) {
 639                 me.doAutoSelect();
 640             }
 641             if (me.typeAhead) {
 642                 me.doTypeAhead();
 643             }
 644         }
 645         return true;
 646     },
 647
 648     // private
 649     getParams: function(queryString) {
 650         var p = {},
 651             pageSize = this.pageSize,
 652             param = this.queryParam;
 653
 654         if (param) {
 655             p[param] = queryString;
 656         }
 657
 658         if (pageSize) {
 659             p.start = 0;
 660             p.limit = pageSize;
 661         }
 662         return p;
 663     },
 664
 665 <span id='Ext-form-field-ComboBox-method-doAutoSelect'>    /**
 666 </span>     * @private
 667      * If the autoSelect config is true, and the picker is open, highlights the first item.
 668      */
 669     doAutoSelect: function() {
 670         var me = this,
 671             picker = me.picker,
 672             lastSelected, itemNode;
 673         if (picker &amp;&amp; me.autoSelect &amp;&amp; me.store.getCount() &gt; 0) {
 674             // Highlight the last selected item and scroll it into view
 675             lastSelected = picker.getSelectionModel().lastSelected;
 676             itemNode = picker.getNode(lastSelected || 0);
 677             if (itemNode) {
 678                 picker.highlightItem(itemNode);
 679                 picker.listEl.scrollChildIntoView(itemNode, false);
 680             }
 681         }
 682     },
 683
 684     doTypeAhead: function() {
 685         if (!this.typeAheadTask) {
 686             this.typeAheadTask = Ext.create('Ext.util.DelayedTask', this.onTypeAhead, this);
 687         }
 688         if (this.lastKey != Ext.EventObject.BACKSPACE &amp;&amp; this.lastKey != Ext.EventObject.DELETE) {
 689             this.typeAheadTask.delay(this.typeAheadDelay);
 690         }
 691     },
 692
 693     onTriggerClick: function() {
 694         var me = this;
 695         if (!me.readOnly &amp;&amp; !me.disabled) {
 696             if (me.isExpanded) {
 697                 me.collapse();
 698             } else {
 699                 me.onFocus({});
 700                 if (me.triggerAction === 'all') {
 701                     me.doQuery(me.allQuery, true);
 702                 } else {
 703                     me.doQuery(me.getRawValue());
 704                 }
 705             }
 706             me.inputEl.focus();
 707         }
 708     },
 709
 710
 711     // store the last key and doQuery if relevant
 712     onKeyUp: function(e, t) {
 713         var me = this,
 714             key = e.getKey();
 715
 716         if (!me.readOnly &amp;&amp; !me.disabled &amp;&amp; me.editable) {
 717             me.lastKey = key;
 718             // we put this in a task so that we can cancel it if a user is
 719             // in and out before the queryDelay elapses
 720
 721             // perform query w/ any normal key or backspace or delete
 722             if (!e.isSpecialKey() || key == e.BACKSPACE || key == e.DELETE) {
 723                 me.doQueryTask.delay(me.queryDelay);
 724             }
 725         }
 726
 727         if (me.enableKeyEvents) {
 728             me.callParent(arguments);
 729         }
 730     },
 731
 732     initEvents: function() {
 733         var me = this;
 734         me.callParent();
 735
 736         /*
 737          * Setup keyboard handling. If enableKeyEvents is true, we already have
 738          * a listener on the inputEl for keyup, so don't create a second.
 739          */
 740         if (!me.enableKeyEvents) {
 741             me.mon(me.inputEl, 'keyup', me.onKeyUp, me);
 742         }
 743     },
 744
 745     createPicker: function() {
 746         var me = this,
 747             picker,
 748             menuCls = Ext.baseCSSPrefix + 'menu',
 749             opts = Ext.apply({
 750                 selModel: {
 751                     mode: me.multiSelect ? 'SIMPLE' : 'SINGLE'
 752                 },
 753                 floating: true,
 754                 hidden: true,
 755                 ownerCt: me.ownerCt,
 756                 cls: me.el.up('.' + menuCls) ? menuCls : '',
 757                 store: me.store,
 758                 displayField: me.displayField,
 759                 focusOnToFront: false,
 760                 pageSize: me.pageSize
 761             }, me.listConfig, me.defaultListConfig);
 762
 763         picker = me.picker = Ext.create('Ext.view.BoundList', opts);
 764
 765         me.mon(picker, {
 766             itemclick: me.onItemClick,
 767             refresh: me.onListRefresh,
 768             scope: me
 769         });
 770
 771         me.mon(picker.getSelectionModel(), {
 772             selectionChange: me.onListSelectionChange,
 773             scope: me
 774         });
 775
 776         return picker;
 777     },
 778
 779     onListRefresh: function() {
 780         this.alignPicker();
 781         this.syncSelection();
 782     },
 783
 784     onItemClick: function(picker, record){
 785         /*
 786          * If we're doing single selection, the selection change events won't fire when
 787          * clicking on the selected element. Detect it here.
 788          */
 789         var me = this,
 790             lastSelection = me.lastSelection,
 791             valueField = me.valueField,
 792             selected;
 793
 794         if (!me.multiSelect &amp;&amp; lastSelection) {
 795             selected = lastSelection[0];
 796             if (record.get(valueField) === selected.get(valueField)) {
 797                 me.collapse();
 798             }
 799         }
 800     },
 801
 802     onListSelectionChange: function(list, selectedRecords) {
 803         var me = this;
 804         // Only react to selection if it is not called from setValue, and if our list is
 805         // expanded (ignores changes to the selection model triggered elsewhere)
 806         if (!me.ignoreSelection &amp;&amp; me.isExpanded) {
 807             if (!me.multiSelect) {
 808                 Ext.defer(me.collapse, 1, me);
 809             }
 810             me.setValue(selectedRecords, false);
 811             if (selectedRecords.length &gt; 0) {
 812                 me.fireEvent('select', me, selectedRecords);
 813             }
 814             me.inputEl.focus();
 815         }
 816     },
 817
 818 <span id='Ext-form-field-ComboBox-method-onExpand'>    /**
 819 </span>     * @private
 820      * Enables the key nav for the BoundList when it is expanded.
 821      */
 822     onExpand: function() {
 823         var me = this,
 824             keyNav = me.listKeyNav,
 825             selectOnTab = me.selectOnTab,
 826             picker = me.getPicker();
 827
 828         // Handle BoundList navigation from the input field. Insert a tab listener specially to enable selectOnTab.
 829         if (keyNav) {
 830             keyNav.enable();
 831         } else {
 832             keyNav = me.listKeyNav = Ext.create('Ext.view.BoundListKeyNav', this.inputEl, {
 833                 boundList: picker,
 834                 forceKeyDown: true,
 835                 tab: function(e) {
 836                     if (selectOnTab) {
 837                         this.selectHighlighted(e);
 838                         me.triggerBlur();
 839                     }
 840                     // Tab key event is allowed to propagate to field
 841                     return true;
 842                 }
 843             });
 844         }
 845
 846         // While list is expanded, stop tab monitoring from Ext.form.field.Trigger so it doesn't short-circuit selectOnTab
 847         if (selectOnTab) {
 848             me.ignoreMonitorTab = true;
 849         }
 850
 851         Ext.defer(keyNav.enable, 1, keyNav); //wait a bit so it doesn't react to the down arrow opening the picker
 852         me.inputEl.focus();
 853     },
 854
 855 <span id='Ext-form-field-ComboBox-method-onCollapse'>    /**
 856 </span>     * @private
 857      * Disables the key nav for the BoundList when it is collapsed.
 858      */
 859     onCollapse: function() {
 860         var me = this,
 861             keyNav = me.listKeyNav;
 862         if (keyNav) {
 863             keyNav.disable();
 864             me.ignoreMonitorTab = false;
 865         }
 866     },
 867
 868 <span id='Ext-form-field-ComboBox-method-select'>    /**
 869 </span>     * Selects an item by a {@link Ext.data.Model Model}, or by a key value.
 870      * @param r
 871      */
 872     select: function(r) {
 873         this.setValue(r, true);
 874     },
 875
 876 <span id='Ext-form-field-ComboBox-method-findRecord'>    /**
 877 </span>     * Find the record by searching for a specific field/value combination
 878      * Returns an Ext.data.Record or false
 879      * @private
 880      */
 881     findRecord: function(field, value) {
 882         var ds = this.store,
 883             idx = ds.findExact(field, value);
 884         return idx !== -1 ? ds.getAt(idx) : false;
 885     },
 886     findRecordByValue: function(value) {
 887         return this.findRecord(this.valueField, value);
 888     },
 889     findRecordByDisplay: function(value) {
 890         return this.findRecord(this.displayField, value);
 891     },
 892
 893 <span id='Ext-form-field-ComboBox-method-setValue'>    /**
 894 </span>     * Sets the specified value(s) into the field. For each value, if a record is found in the {@link #store} that
 895      * matches based on the {@link #valueField}, then that record's {@link #displayField} will be displayed in the
 896      * field.  If no match is found, and the {@link #valueNotFoundText} config option is defined, then that will be
 897      * displayed as the default field text. Otherwise a blank value will be shown, although the value will still be set.
 898      * @param {String|Array} value The value(s) to be set. Can be either a single String or {@link Ext.data.Model},
 899      * or an Array of Strings or Models.
 900      * @return {Ext.form.field.Field} this
 901      */
 902     setValue: function(value, doSelect) {
 903         var me = this,
 904             valueNotFoundText = me.valueNotFoundText,
 905             inputEl = me.inputEl,
 906             i, len, record,
 907             models = [],
 908             displayTplData = [],
 909             processedValue = [];
 910
 911         if (me.store.loading) {
 912             // Called while the Store is loading. Ensure it is processed by the onLoad method.
 913             me.value = value;
 914             return me;
 915         }
 916
 917         // This method processes multi-values, so ensure value is an array.
 918         value = Ext.Array.from(value);
 919
 920         // Loop through values
 921         for (i = 0, len = value.length; i &lt; len; i++) {
 922             record = value[i];
 923             if (!record || !record.isModel) {
 924                 record = me.findRecordByValue(record);
 925             }
 926             // record found, select it.
 927             if (record) {
 928                 models.push(record);
 929                 displayTplData.push(record.data);
 930                 processedValue.push(record.get(me.valueField));
 931             }
 932             // record was not found, this could happen because
 933             // store is not loaded or they set a value not in the store
 934             else {
 935                 // if valueNotFoundText is defined, display it, otherwise display nothing for this value
 936                 if (Ext.isDefined(valueNotFoundText)) {
 937                     displayTplData.push(valueNotFoundText);
 938                 }
 939                 processedValue.push(value[i]);
 940             }
 941         }
 942
 943         // Set the value of this field. If we are multiselecting, then that is an array.
 944         me.value = me.multiSelect ? processedValue : processedValue[0];
 945         if (!Ext.isDefined(me.value)) {
 946             me.value = null;
 947         }
 948         me.displayTplData = displayTplData; //store for getDisplayValue method
 949         me.lastSelection = me.valueModels = models;
 950
 951         if (inputEl &amp;&amp; me.emptyText &amp;&amp; !Ext.isEmpty(value)) {
 952             inputEl.removeCls(me.emptyCls);
 953         }
 954
 955         // Calculate raw value from the collection of Model data
 956         me.setRawValue(me.getDisplayValue());
 957         me.checkChange();
 958
 959         if (doSelect !== false) {
 960             me.syncSelection();
 961         }
 962         me.applyEmptyText();
 963
 964         return me;
 965     },
 966
 967 <span id='Ext-form-field-ComboBox-method-getDisplayValue'>    /**
 968 </span>     * @private Generate the string value to be displayed in the text field for the currently stored value
 969      */
 970     getDisplayValue: function() {
 971         return this.displayTpl.apply(this.displayTplData);
 972     },
 973
 974     getValue: function() {
 975         // If the user has not changed the raw field value since a value was selected from the list,
 976         // then return the structured value from the selection. If the raw field value is different
 977         // than what would be displayed due to selection, return that raw value.
 978         var me = this,
 979             picker = me.picker,
 980             rawValue = me.getRawValue(), //current value of text field
 981             value = me.value; //stored value from last selection or setValue() call
 982
 983         if (me.getDisplayValue() !== rawValue) {
 984             value = rawValue;
 985             me.value = me.displayTplData = me.valueModels = null;
 986             if (picker) {
 987                 me.ignoreSelection++;
 988                 picker.getSelectionModel().deselectAll();
 989                 me.ignoreSelection--;
 990             }
 991         }
 992
 993         return value;
 994     },
 995
 996     getSubmitValue: function() {
 997         return this.getValue();
 998     },
 999
1000     isEqual: function(v1, v2) {
1001         var fromArray = Ext.Array.from,
1002             i, len;
1003
1004         v1 = fromArray(v1);
1005         v2 = fromArray(v2);
1006         len = v1.length;
1007
1008         if (len !== v2.length) {
1009             return false;
1010         }
1011
1012         for(i = 0; i &lt; len; i++) {
1013             if (v2[i] !== v1[i]) {
1014                 return false;
1015             }
1016         }
1017
1018         return true;
1019     },
1020
1021 <span id='Ext-form-field-ComboBox-method-clearValue'>    /**
1022 </span>     * Clears any value currently set in the ComboBox.
1023      */
1024     clearValue: function() {
1025         this.setValue([]);
1026     },
1027
1028 <span id='Ext-form-field-ComboBox-method-syncSelection'>    /**
1029 </span>     * @private Synchronizes the selection in the picker to match the current value of the combobox.
1030      */
1031     syncSelection: function() {
1032         var me = this,
1033             ExtArray = Ext.Array,
1034             picker = me.picker,
1035             selection, selModel;
1036         if (picker) {
1037             // From the value, find the Models that are in the store's current data
1038             selection = [];
1039             ExtArray.forEach(me.valueModels || [], function(value) {
1040                 if (value &amp;&amp; value.isModel &amp;&amp; me.store.indexOf(value) &gt;= 0) {
1041                     selection.push(value);
1042                 }
1043             });
1044
1045             // Update the selection to match
1046             me.ignoreSelection++;
1047             selModel = picker.getSelectionModel();
1048             selModel.deselectAll();
1049             if (selection.length) {
1050                 selModel.select(selection);
1051             }
1052             me.ignoreSelection--;
1053         }
1054     }
1055 });
1056 </pre>
1057 </body>
1058 </html>