Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / Picker.html
index f8c8c47..6822167 100644 (file)
@@ -1,19 +1,30 @@
-<!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'>/**
-</span></span> * @class Ext.form.field.Picker
- * @extends Ext.form.field.Trigger
- * &lt;p&gt;An abstract class for fields that have a single trigger which opens a &quot;picker&quot; popup below
- * the field, e.g. a combobox menu list or a date picker. It provides a base implementation for
- * toggling the picker's visibility when the trigger is clicked, as well as keyboard navigation
- * and some basic events. Sizing and alignment of the picker can be controlled via the {@link #matchFieldWidth}
- * and {@link #pickerAlign}/{@link #pickerOffset} config properties respectively.&lt;/p&gt;
- * &lt;p&gt;You would not normally use this class directly, but instead use it as the parent class for
- * a specific picker field implementation. Subclasses must implement the {@link #createPicker} method
- * to create a picker component appropriate for the field.&lt;/p&gt;
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+  <title>The source code</title>
+  <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
+  <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
+  <style type="text/css">
+    .highlight { display: block; background-color: #ddd; }
+  </style>
+  <script type="text/javascript">
+    function highlight() {
+      document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
+    }
+  </script>
+</head>
+<body onload="prettyPrint(); highlight();">
+  <pre class="prettyprint lang-js"><span id='Ext-form-field-Picker'>/**
+</span> * An abstract class for fields that have a single trigger which opens a &quot;picker&quot; popup below the field, e.g. a combobox
+ * menu list or a date picker. It provides a base implementation for toggling the picker's visibility when the trigger
+ * is clicked, as well as keyboard navigation and some basic events. Sizing and alignment of the picker can be
+ * controlled via the {@link #matchFieldWidth} and {@link #pickerAlign}/{@link #pickerOffset} config properties
+ * respectively.
  *
- * @xtype pickerfield
- * @constructor
- * Create a new picker field
- * @param {Object} config
+ * You would not normally use this class directly, but instead use it as the parent class for a specific picker field
+ * implementation. Subclasses must implement the {@link #createPicker} method to create a picker component appropriate
+ * for the field.
  */
 Ext.define('Ext.form.field.Picker', {
     extend: 'Ext.form.field.Trigger',
@@ -21,44 +32,41 @@ Ext.define('Ext.form.field.Picker', {
     alternateClassName: 'Ext.form.Picker',
     requires: ['Ext.util.KeyNav'],
 
-<span id='Ext-form.field.Picker-cfg-matchFieldWidth'>    /**
+<span id='Ext-form-field-Picker-cfg-matchFieldWidth'>    /**
 </span>     * @cfg {Boolean} matchFieldWidth
-     * Whether the picker dropdown's width should be explicitly set to match the width of the field.
-     * Defaults to &lt;tt&gt;true&lt;/tt&gt;.
+     * Whether the picker dropdown's width should be explicitly set to match the width of the field. Defaults to true.
      */
     matchFieldWidth: true,
 
-<span id='Ext-form.field.Picker-cfg-pickerAlign'>    /**
+<span id='Ext-form-field-Picker-cfg-pickerAlign'>    /**
 </span>     * @cfg {String} pickerAlign
-     * The {@link Ext.core.Element#alignTo alignment position} with which to align the picker. Defaults
-     * to &lt;tt&gt;&quot;tl-bl?&quot;&lt;/tt&gt;
+     * The {@link Ext.Element#alignTo alignment position} with which to align the picker. Defaults to &quot;tl-bl?&quot;
      */
     pickerAlign: 'tl-bl?',
 
-<span id='Ext-form.field.Picker-cfg-pickerOffset'>    /**
-</span>     * @cfg {Array} pickerOffset
+<span id='Ext-form-field-Picker-cfg-pickerOffset'>    /**
+</span>     * @cfg {Number[]} pickerOffset
      * An offset [x,y] to use in addition to the {@link #pickerAlign} when positioning the picker.
      * Defaults to undefined.
      */
 
-<span id='Ext-form.field.Picker-cfg-openCls'>    /**
+<span id='Ext-form-field-Picker-cfg-openCls'>    /**
 </span>     * @cfg {String} openCls
-     * A class to be added to the field's {@link #bodyEl} element when the picker is opened. Defaults
-     * to 'x-pickerfield-open'.
+     * A class to be added to the field's {@link #bodyEl} element when the picker is opened.
+     * Defaults to 'x-pickerfield-open'.
      */
     openCls: Ext.baseCSSPrefix + 'pickerfield-open',
 
-<span id='Ext-form.field.Picker-property-isExpanded'>    /**
-</span>     * @property isExpanded
-     * @type Boolean
+<span id='Ext-form-field-Picker-property-isExpanded'>    /**
+</span>     * @property {Boolean} isExpanded
      * True if the picker is currently expanded, false if not.
      */
 
-<span id='Ext-form.field.Picker-cfg-editable'>    /**
-</span>     * @cfg {Boolean} editable &lt;tt&gt;false&lt;/tt&gt; to prevent the user from typing text directly into the field;
-     * the field can only have its value set via selecting a value from the picker. In this state, the picker
-     * can also be opened by clicking directly on the input field itself.
-     * (defaults to &lt;tt&gt;true&lt;/tt&gt;).
+<span id='Ext-form-field-Picker-cfg-editable'>    /**
+</span>     * @cfg {Boolean} editable
+     * False to prevent the user from typing text directly into the field; the field can only have its value set via
+     * selecting a value from the picker. In this state, the picker can also be opened by clicking directly on the input
+     * field itself.
      */
     editable: true,
 
@@ -68,23 +76,23 @@ Ext.define('Ext.form.field.Picker', {
 
         // Custom events
         this.addEvents(
-<span id='Ext-form.field.Picker-event-expand'>            /**
+<span id='Ext-form-field-Picker-event-expand'>            /**
 </span>             * @event expand
              * Fires when the field's picker is expanded.
              * @param {Ext.form.field.Picker} field This field instance
              */
             'expand',
-<span id='Ext-form.field.Picker-event-collapse'>            /**
+<span id='Ext-form-field-Picker-event-collapse'>            /**
 </span>             * @event collapse
              * Fires when the field's picker is collapsed.
              * @param {Ext.form.field.Picker} field This field instance
              */
             'collapse',
-<span id='Ext-form.field.Picker-event-select'>            /**
+<span id='Ext-form-field-Picker-event-select'>            /**
 </span>             * @event select
              * Fires when a value is selected via the picker.
              * @param {Ext.form.field.Picker} field This field instance
-             * @param {Mixed} value The value that was selected. The exact type of this value is dependent on
+             * @param {Object} value The value that was selected. The exact type of this value is dependent on
              * the individual field and picker implementations.
              */
             'select'
@@ -122,8 +130,8 @@ Ext.define('Ext.form.field.Picker', {
     },
 
 
-<span id='Ext-form.field.Picker-method-expand'>    /**
-</span>     * Expand this field's picker dropdown.
+<span id='Ext-form-field-Picker-method-expand'>    /**
+</span>     * Expands this field's picker dropdown.
      */
     expand: function() {
         var me = this,
@@ -146,7 +154,7 @@ Ext.define('Ext.form.field.Picker', {
                 mousedown: collapseIf,
                 scope: me
             });
-
+            Ext.EventManager.onWindowResize(me.alignPicker, me);
             me.fireEvent('expand', me);
             me.onExpand();
         }
@@ -154,35 +162,46 @@ Ext.define('Ext.form.field.Picker', {
 
     onExpand: Ext.emptyFn,
 
-<span id='Ext-form.field.Picker-method-alignPicker'>    /**
-</span>     * @protected
-     * Aligns the picker to the
+<span id='Ext-form-field-Picker-method-alignPicker'>    /**
+</span>     * Aligns the picker to the input element
+     * @protected
      */
     alignPicker: function() {
         var me = this,
-            picker, isAbove,
-            aboveSfx = '-above';
+            picker;
 
-        if (this.isExpanded) {
+        if (me.isExpanded) {
             picker = me.getPicker();
             if (me.matchFieldWidth) {
                 // Auto the height (it will be constrained by min and max width) unless there are no records to display.
                 picker.setSize(me.bodyEl.getWidth(), picker.store &amp;&amp; picker.store.getCount() ? null : 0);
             }
             if (picker.isFloating()) {
-                picker.alignTo(me.inputEl, me.pickerAlign, me.pickerOffset);
-
-                // add the {openCls}-above class if the picker was aligned above
-                // the field due to hitting the bottom of the viewport
-                isAbove = picker.el.getY() &lt; me.inputEl.getY();
-                me.bodyEl[isAbove ? 'addCls' : 'removeCls'](me.openCls + aboveSfx);
-                picker.el[isAbove ? 'addCls' : 'removeCls'](picker.baseCls + aboveSfx);
+                me.doAlign();
             }
         }
     },
 
-<span id='Ext-form.field.Picker-method-collapse'>    /**
-</span>     * Collapse this field's picker dropdown.
+<span id='Ext-form-field-Picker-method-doAlign'>    /**
+</span>     * Performs the alignment on the picker using the class defaults
+     * @private
+     */
+    doAlign: function(){
+        var me = this,
+            picker = me.picker,
+            aboveSfx = '-above',
+            isAbove;
+
+        me.picker.alignTo(me.inputEl, me.pickerAlign, me.pickerOffset);
+        // add the {openCls}-above class if the picker was aligned above
+        // the field due to hitting the bottom of the viewport
+        isAbove = picker.el.getY() &lt; me.inputEl.getY();
+        me.bodyEl[isAbove ? 'addCls' : 'removeCls'](me.openCls + aboveSfx);
+        picker[isAbove ? 'addCls' : 'removeCls'](picker.baseCls + aboveSfx);
+    },
+
+<span id='Ext-form-field-Picker-method-collapse'>    /**
+</span>     * Collapses this field's picker dropdown.
      */
     collapse: function() {
         if (this.isExpanded &amp;&amp; !this.isDestroyed) {
@@ -204,7 +223,7 @@ Ext.define('Ext.form.field.Picker', {
             // remove event listeners
             doc.un('mousewheel', collapseIf, me);
             doc.un('mousedown', collapseIf, me);
-
+            Ext.EventManager.removeResizeListener(me.alignPicker, me);
             me.fireEvent('collapse', me);
             me.onCollapse();
         }
@@ -213,7 +232,7 @@ Ext.define('Ext.form.field.Picker', {
     onCollapse: Ext.emptyFn,
 
 
-<span id='Ext-form.field.Picker-method-collapseIf'>    /**
+<span id='Ext-form-field-Picker-method-collapseIf'>    /**
 </span>     * @private
      * Runs on mousewheel and mousedown of doc to check to see if we should collapse the picker
      */
@@ -224,8 +243,8 @@ Ext.define('Ext.form.field.Picker', {
         }
     },
 
-<span id='Ext-form.field.Picker-method-getPicker'>    /**
-</span>     * Return a reference to the picker component for this field, creating it if necessary by
+<span id='Ext-form-field-Picker-method-getPicker'>    /**
+</span>     * Returns a reference to the picker component for this field, creating it if necessary by
      * calling {@link #createPicker}.
      * @return {Ext.Component} The picker component
      */
@@ -234,16 +253,17 @@ Ext.define('Ext.form.field.Picker', {
         return me.picker || (me.picker = me.createPicker());
     },
 
-<span id='Ext-form.field.Picker-property-createPicker'>    /**
-</span>     * Create and return the component to be used as this field's picker. Must be implemented
-     * by subclasses of Picker.
-     * @return {Ext.Component} The picker component
+<span id='Ext-form-field-Picker-method-createPicker'>    /**
+</span>     * @method
+     * Creates and returns the component to be used as this field's picker. Must be implemented by subclasses of Picker.
+     * The current field should also be passed as a configuration option to the picker component as the pickerField
+     * property.
      */
     createPicker: Ext.emptyFn,
 
-<span id='Ext-form.field.Picker-method-onTriggerClick'>    /**
-</span>     * Handles the trigger click; by default toggles between expanding and collapsing the
-     * picker component.
+<span id='Ext-form-field-Picker-method-onTriggerClick'>    /**
+</span>     * Handles the trigger click; by default toggles between expanding and collapsing the picker component.
+     * @protected
      */
     onTriggerClick: function() {
         var me = this;
@@ -267,11 +287,20 @@ Ext.define('Ext.form.field.Picker', {
     },
 
     onDestroy : function(){
-        var me = this;
-        Ext.destroy(me.picker, me.keyNav);
+        var me = this,
+            picker = me.picker;
+
+        Ext.EventManager.removeResizeListener(me.alignPicker, me);
+        Ext.destroy(me.keyNav);
+        if (picker) {
+            delete picker.pickerField;
+            picker.destroy();
+        }
         me.callParent();
     }
 
 });
 
-</pre></pre></body></html>
\ No newline at end of file
+</pre>
+</body>
+</html>