docs/source/Picker.html

   1 <!DOCTYPE html><html><head><title>Sencha Documentation Project</title><link rel="stylesheet" href="../reset.css" type="text/css"><link rel="stylesheet" href="../prettify.css" type="text/css"><link rel="stylesheet" href="../prettify_sa.css" type="text/css"><script type="text/javascript" src="../prettify.js"></script></head><body onload="prettyPrint()"><pre class="prettyprint"><pre><span id='Ext-form.field.Picker-method-constructor'><span id='Ext-form.field.Picker'>/**
   2 </span></span> * @class Ext.form.field.Picker
   3  * @extends Ext.form.field.Trigger
   4  * &lt;p&gt;An abstract class for fields that have a single trigger which opens a &quot;picker&quot; popup below
   5  * the field, e.g. a combobox menu list or a date picker. It provides a base implementation for
   6  * toggling the picker's visibility when the trigger is clicked, as well as keyboard navigation
   7  * and some basic events. Sizing and alignment of the picker can be controlled via the {@link #matchFieldWidth}
   8  * and {@link #pickerAlign}/{@link #pickerOffset} config properties respectively.&lt;/p&gt;
   9  * &lt;p&gt;You would not normally use this class directly, but instead use it as the parent class for
  10  * a specific picker field implementation. Subclasses must implement the {@link #createPicker} method
  11  * to create a picker component appropriate for the field.&lt;/p&gt;
  12  *
  13  * @xtype pickerfield
  14  * @constructor
  15  * Create a new picker field
  16  * @param {Object} config
  17  */
  18 Ext.define('Ext.form.field.Picker', {
  19     extend: 'Ext.form.field.Trigger',
  20     alias: 'widget.pickerfield',
  21     alternateClassName: 'Ext.form.Picker',
  22     requires: ['Ext.util.KeyNav'],
  23
  24 <span id='Ext-form.field.Picker-cfg-matchFieldWidth'>    /**
  25 </span>     * @cfg {Boolean} matchFieldWidth
  26      * Whether the picker dropdown's width should be explicitly set to match the width of the field.
  27      * Defaults to &lt;tt&gt;true&lt;/tt&gt;.
  28      */
  29     matchFieldWidth: true,
  30
  31 <span id='Ext-form.field.Picker-cfg-pickerAlign'>    /**
  32 </span>     * @cfg {String} pickerAlign
  33      * The {@link Ext.core.Element#alignTo alignment position} with which to align the picker. Defaults
  34      * to &lt;tt&gt;&quot;tl-bl?&quot;&lt;/tt&gt;
  35      */
  36     pickerAlign: 'tl-bl?',
  37
  38 <span id='Ext-form.field.Picker-cfg-pickerOffset'>    /**
  39 </span>     * @cfg {Array} pickerOffset
  40      * An offset [x,y] to use in addition to the {@link #pickerAlign} when positioning the picker.
  41      * Defaults to undefined.
  42      */
  43
  44 <span id='Ext-form.field.Picker-cfg-openCls'>    /**
  45 </span>     * @cfg {String} openCls
  46      * A class to be added to the field's {@link #bodyEl} element when the picker is opened. Defaults
  47      * to 'x-pickerfield-open'.
  48      */
  49     openCls: Ext.baseCSSPrefix + 'pickerfield-open',
  50
  51 <span id='Ext-form.field.Picker-property-isExpanded'>    /**
  52 </span>     * @property isExpanded
  53      * @type Boolean
  54      * True if the picker is currently expanded, false if not.
  55      */
  56
  57 <span id='Ext-form.field.Picker-cfg-editable'>    /**
  58 </span>     * @cfg {Boolean} editable &lt;tt&gt;false&lt;/tt&gt; to prevent the user from typing text directly into the field;
  59      * the field can only have its value set via selecting a value from the picker. In this state, the picker
  60      * can also be opened by clicking directly on the input field itself.
  61      * (defaults to &lt;tt&gt;true&lt;/tt&gt;).
  62      */
  63     editable: true,
  64
  65
  66     initComponent: function() {
  67         this.callParent();
  68
  69         // Custom events
  70         this.addEvents(
  71 <span id='Ext-form.field.Picker-event-expand'>            /**
  72 </span>             * @event expand
  73              * Fires when the field's picker is expanded.
  74              * @param {Ext.form.field.Picker} field This field instance
  75              */
  76             'expand',
  77 <span id='Ext-form.field.Picker-event-collapse'>            /**
  78 </span>             * @event collapse
  79              * Fires when the field's picker is collapsed.
  80              * @param {Ext.form.field.Picker} field This field instance
  81              */
  82             'collapse',
  83 <span id='Ext-form.field.Picker-event-select'>            /**
  84 </span>             * @event select
  85              * Fires when a value is selected via the picker.
  86              * @param {Ext.form.field.Picker} field This field instance
  87              * @param {Mixed} value The value that was selected. The exact type of this value is dependent on
  88              * the individual field and picker implementations.
  89              */
  90             'select'
  91         );
  92     },
  93
  94
  95     initEvents: function() {
  96         var me = this;
  97         me.callParent();
  98
  99         // Add handlers for keys to expand/collapse the picker
 100         me.keyNav = Ext.create('Ext.util.KeyNav', me.inputEl, {
 101             down: function() {
 102                 if (!me.isExpanded) {
 103                     // Don't call expand() directly as there may be additional processing involved before
 104                     // expanding, e.g. in the case of a ComboBox query.
 105                     me.onTriggerClick();
 106                 }
 107             },
 108             esc: me.collapse,
 109             scope: me,
 110             forceKeyDown: true
 111         });
 112
 113         // Non-editable allows opening the picker by clicking the field
 114         if (!me.editable) {
 115             me.mon(me.inputEl, 'click', me.onTriggerClick, me);
 116         }
 117
 118         // Disable native browser autocomplete
 119         if (Ext.isGecko) {
 120             me.inputEl.dom.setAttribute('autocomplete', 'off');
 121         }
 122     },
 123
 124
 125 <span id='Ext-form.field.Picker-method-expand'>    /**
 126 </span>     * Expand this field's picker dropdown.
 127      */
 128     expand: function() {
 129         var me = this,
 130             bodyEl, picker, collapseIf;
 131
 132         if (me.rendered &amp;&amp; !me.isExpanded &amp;&amp; !me.isDestroyed) {
 133             bodyEl = me.bodyEl;
 134             picker = me.getPicker();
 135             collapseIf = me.collapseIf;
 136
 137             // show the picker and set isExpanded flag
 138             picker.show();
 139             me.isExpanded = true;
 140             me.alignPicker();
 141             bodyEl.addCls(me.openCls);
 142
 143             // monitor clicking and mousewheel
 144             me.mon(Ext.getDoc(), {
 145                 mousewheel: collapseIf,
 146                 mousedown: collapseIf,
 147                 scope: me
 148             });
 149
 150             me.fireEvent('expand', me);
 151             me.onExpand();
 152         }
 153     },
 154
 155     onExpand: Ext.emptyFn,
 156
 157 <span id='Ext-form.field.Picker-method-alignPicker'>    /**
 158 </span>     * @protected
 159      * Aligns the picker to the
 160      */
 161     alignPicker: function() {
 162         var me = this,
 163             picker, isAbove,
 164             aboveSfx = '-above';
 165
 166         if (this.isExpanded) {
 167             picker = me.getPicker();
 168             if (me.matchFieldWidth) {
 169                 // Auto the height (it will be constrained by min and max width) unless there are no records to display.
 170                 picker.setSize(me.bodyEl.getWidth(), picker.store &amp;&amp; picker.store.getCount() ? null : 0);
 171             }
 172             if (picker.isFloating()) {
 173                 picker.alignTo(me.inputEl, me.pickerAlign, me.pickerOffset);
 174
 175                 // add the {openCls}-above class if the picker was aligned above
 176                 // the field due to hitting the bottom of the viewport
 177                 isAbove = picker.el.getY() &lt; me.inputEl.getY();
 178                 me.bodyEl[isAbove ? 'addCls' : 'removeCls'](me.openCls + aboveSfx);
 179                 picker.el[isAbove ? 'addCls' : 'removeCls'](picker.baseCls + aboveSfx);
 180             }
 181         }
 182     },
 183
 184 <span id='Ext-form.field.Picker-method-collapse'>    /**
 185 </span>     * Collapse this field's picker dropdown.
 186      */
 187     collapse: function() {
 188         if (this.isExpanded &amp;&amp; !this.isDestroyed) {
 189             var me = this,
 190                 openCls = me.openCls,
 191                 picker = me.picker,
 192                 doc = Ext.getDoc(),
 193                 collapseIf = me.collapseIf,
 194                 aboveSfx = '-above';
 195
 196             // hide the picker and set isExpanded flag
 197             picker.hide();
 198             me.isExpanded = false;
 199
 200             // remove the openCls
 201             me.bodyEl.removeCls([openCls, openCls + aboveSfx]);
 202             picker.el.removeCls(picker.baseCls + aboveSfx);
 203
 204             // remove event listeners
 205             doc.un('mousewheel', collapseIf, me);
 206             doc.un('mousedown', collapseIf, me);
 207
 208             me.fireEvent('collapse', me);
 209             me.onCollapse();
 210         }
 211     },
 212
 213     onCollapse: Ext.emptyFn,
 214
 215
 216 <span id='Ext-form.field.Picker-method-collapseIf'>    /**
 217 </span>     * @private
 218      * Runs on mousewheel and mousedown of doc to check to see if we should collapse the picker
 219      */
 220     collapseIf: function(e) {
 221         var me = this;
 222         if (!me.isDestroyed &amp;&amp; !e.within(me.bodyEl, false, true) &amp;&amp; !e.within(me.picker.el, false, true)) {
 223             me.collapse();
 224         }
 225     },
 226
 227 <span id='Ext-form.field.Picker-method-getPicker'>    /**
 228 </span>     * Return a reference to the picker component for this field, creating it if necessary by
 229      * calling {@link #createPicker}.
 230      * @return {Ext.Component} The picker component
 231      */
 232     getPicker: function() {
 233         var me = this;
 234         return me.picker || (me.picker = me.createPicker());
 235     },
 236
 237 <span id='Ext-form.field.Picker-property-createPicker'>    /**
 238 </span>     * Create and return the component to be used as this field's picker. Must be implemented
 239      * by subclasses of Picker.
 240      * @return {Ext.Component} The picker component
 241      */
 242     createPicker: Ext.emptyFn,
 243
 244 <span id='Ext-form.field.Picker-method-onTriggerClick'>    /**
 245 </span>     * Handles the trigger click; by default toggles between expanding and collapsing the
 246      * picker component.
 247      */
 248     onTriggerClick: function() {
 249         var me = this;
 250         if (!me.readOnly &amp;&amp; !me.disabled) {
 251             if (me.isExpanded) {
 252                 me.collapse();
 253             } else {
 254                 me.expand();
 255             }
 256             me.inputEl.focus();
 257         }
 258     },
 259
 260     mimicBlur: function(e) {
 261         var me = this,
 262             picker = me.picker;
 263         // ignore mousedown events within the picker element
 264         if (!picker || !e.within(picker.el, false, true)) {
 265             me.callParent(arguments);
 266         }
 267     },
 268
 269     onDestroy : function(){
 270         var me = this;
 271         Ext.destroy(me.picker, me.keyNav);
 272         me.callParent();
 273     }
 274
 275 });
 276
 277 </pre></pre></body></html>