Upgrade to ExtJS 3.2.1 - Released 04/27/2010
[extjs.git] / docs / source / Editor.html
index a5282b4..e96ae8a 100644 (file)
@@ -1,11 +1,18 @@
-<html>\r
-<head>\r
-  <title>The source code</title>\r
-    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
-    <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
-</head>\r
-<body  onload="prettyPrint();">\r
-    <pre class="prettyprint lang-js"><div id="cls-Ext.Editor"></div>/**
+<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>
+</head>
+<body  onload="prettyPrint();">
+    <pre class="prettyprint lang-js">/*!
+ * Ext JS Library 3.2.1
+ * Copyright(c) 2006-2010 Ext JS, Inc.
+ * licensing@extjs.com
+ * http://www.extjs.com/license
+ */
+<div id="cls-Ext.Editor"></div>/**
  * @class Ext.Editor
  * @extends Ext.Component
  * A base editor field that handles displaying/hiding on demand and has some built-in sizing and event handling logic.
  * @class Ext.Editor
  * @extends Ext.Component
  * A base editor field that handles displaying/hiding on demand and has some built-in sizing and event handling logic.
@@ -33,12 +40,13 @@ Ext.extend(Ext.Editor, Ext.Component, {
     <div id="cfg-Ext.Editor-allowBlur"></div>/**
      * @cfg {Boolean} allowBlur
      * True to {@link #completeEdit complete the editing process} if in edit mode when the
     <div id="cfg-Ext.Editor-allowBlur"></div>/**
      * @cfg {Boolean} allowBlur
      * True to {@link #completeEdit complete the editing process} if in edit mode when the
-     * field is blurred. Defaults to <tt>false</tt>.
+     * field is blurred. Defaults to <tt>true</tt>.
      */
      */
+    allowBlur: true,
     <div id="cfg-Ext.Editor-autoSize"></div>/**
      * @cfg {Boolean/String} autoSize
     <div id="cfg-Ext.Editor-autoSize"></div>/**
      * @cfg {Boolean/String} autoSize
-     * True for the editor to automatically adopt the size of the element being edited, "width" to adopt the width only,
-     * or "height" to adopt the height only (defaults to false)
+     * True for the editor to automatically adopt the size of the underlying field, "width" to adopt the width only,
+     * or "height" to adopt the height only, "none" to always use the field dimensions. (defaults to false)
      */
     <div id="cfg-Ext.Editor-revertInvalid"></div>/**
      * @cfg {Boolean} revertInvalid
      */
     <div id="cfg-Ext.Editor-revertInvalid"></div>/**
      * @cfg {Boolean} revertInvalid
@@ -65,6 +73,11 @@ Ext.extend(Ext.Editor, Ext.Component, {
      * The position to align to (see {@link Ext.Element#alignTo} for more details, defaults to "c-c?").
      */
     alignment: "c-c?",
      * The position to align to (see {@link Ext.Element#alignTo} for more details, defaults to "c-c?").
      */
     alignment: "c-c?",
+    <div id="cfg-Ext.Editor-offsets"></div>/**
+     * @cfg {Array} offsets
+     * The offsets to use when aligning (see {@link Ext.Element#alignTo} for more details. Defaults to <tt>[0, 0]</tt>.
+     */
+    offsets: [0, 0],
     <div id="cfg-Ext.Editor-shadow"></div>/**
      * @cfg {Boolean/String} shadow "sides" for sides/bottom only, "frame" for 4-way shadow, and "drop"
      * for bottom-right shadow (defaults to "frame")
     <div id="cfg-Ext.Editor-shadow"></div>/**
      * @cfg {Boolean/String} shadow "sides" for sides/bottom only, "frame" for 4-way shadow, and "drop"
      * for bottom-right shadow (defaults to "frame")
@@ -79,13 +92,13 @@ Ext.extend(Ext.Editor, Ext.Component, {
      */
     swallowKeys : true,
     <div id="cfg-Ext.Editor-completeOnEnter"></div>/**
      */
     swallowKeys : true,
     <div id="cfg-Ext.Editor-completeOnEnter"></div>/**
-     * @cfg {Boolean} completeOnEnter True to complete the edit when the enter key is pressed (defaults to false)
+     * @cfg {Boolean} completeOnEnter True to complete the edit when the enter key is pressed. Defaults to <tt>true</tt>.
      */
      */
-    completeOnEnter : false,
+    completeOnEnter : true,
     <div id="cfg-Ext.Editor-cancelOnEsc"></div>/**
     <div id="cfg-Ext.Editor-cancelOnEsc"></div>/**
-     * @cfg {Boolean} cancelOnEsc True to cancel the edit when the escape key is pressed (defaults to false)
+     * @cfg {Boolean} cancelOnEsc True to cancel the edit when the escape key is pressed. Defaults to <tt>true</tt>.
      */
      */
-    cancelOnEsc : false,
+    cancelOnEsc : true,
     <div id="cfg-Ext.Editor-updateEl"></div>/**
      * @cfg {Boolean} updateEl True to update the innerHTML of the bound element when the update completes (defaults to false)
      */
     <div id="cfg-Ext.Editor-updateEl"></div>/**
      * @cfg {Boolean} updateEl True to update the innerHTML of the bound element when the update completes (defaults to false)
      */
@@ -167,35 +180,41 @@ Ext.extend(Ext.Editor, Ext.Component, {
             this.field.msgTarget = 'qtip';
         }
         this.field.inEditor = true;
             this.field.msgTarget = 'qtip';
         }
         this.field.inEditor = true;
-        this.field.render(this.el);
-        if(Ext.isGecko){
-            this.field.el.dom.setAttribute('autocomplete', 'off');
+        this.mon(this.field, {
+            scope: this,
+            blur: this.onBlur,
+            specialkey: this.onSpecialKey
+        });
+        if(this.field.grow){
+            this.mon(this.field, "autosize", this.el.sync,  this.el, {delay:1});
         }
         }
-        this.mon(this.field, "specialkey", this.onSpecialKey, this);
+        this.field.render(this.el).show();
+        this.field.getEl().dom.name = '';
         if(this.swallowKeys){
         if(this.swallowKeys){
-            this.field.el.swallowEvent(['keydown','keypress']);
-        }
-        this.field.show();
-        this.mon(this.field, "blur", this.onBlur, this);
-        if(this.field.grow){
-               this.mon(this.field, "autosize", this.el.sync,  this.el, {delay:1});
+            this.field.el.swallowEvent([
+                'keypress', // *** Opera
+                'keydown'   // *** all other browsers
+            ]);
         }
     },
 
     // private
     onSpecialKey : function(field, e){
         }
     },
 
     // private
     onSpecialKey : function(field, e){
-        var key = e.getKey();
-        if(this.completeOnEnter && key == e.ENTER){
+        var key = e.getKey(),
+            complete = this.completeOnEnter && key == e.ENTER,
+            cancel = this.cancelOnEsc && key == e.ESC;
+        if(complete || cancel){
             e.stopEvent();
             e.stopEvent();
-            this.completeEdit();
-        }else if(this.cancelOnEsc && key == e.ESC){
-            this.cancelEdit();
-        }else{
-            this.fireEvent('specialkey', field, e);
-        }
-        if(this.field.triggerBlur && (key == e.ENTER || key == e.ESC || key == e.TAB)){
-            this.field.triggerBlur();
+            if(complete){
+                this.completeEdit();
+            }else{
+                this.cancelEdit();
+            }
+            if(field.triggerBlur){
+                field.triggerBlur();
+            }
         }
         }
+        this.fireEvent('specialkey', field, e);
     },
 
     <div id="method-Ext.Editor-startEdit"></div>/**
     },
 
     <div id="method-Ext.Editor-startEdit"></div>/**
@@ -213,30 +232,34 @@ Ext.extend(Ext.Editor, Ext.Component, {
         if(!this.rendered){
             this.render(this.parentEl || document.body);
         }
         if(!this.rendered){
             this.render(this.parentEl || document.body);
         }
-        if(this.fireEvent("beforestartedit", this, this.boundEl, v) === false){
-            return;
+        if(this.fireEvent("beforestartedit", this, this.boundEl, v) !== false){
+            this.startValue = v;
+            this.field.reset();
+            this.field.setValue(v);
+            this.realign(true);
+            this.editing = true;
+            this.show();
         }
         }
-        this.startValue = v;
-        this.field.setValue(v);
-        this.doAutoSize();
-        this.el.alignTo(this.boundEl, this.alignment);
-        this.editing = true;
-        this.show();
     },
 
     // private
     doAutoSize : function(){
         if(this.autoSize){
     },
 
     // private
     doAutoSize : function(){
         if(this.autoSize){
-            var sz = this.boundEl.getSize();
+            var sz = this.boundEl.getSize(),
+                fs = this.field.getSize();
+
             switch(this.autoSize){
                 case "width":
             switch(this.autoSize){
                 case "width":
-                    this.setSize(sz.width,  "");
-                break;
+                    this.setSize(sz.width, fs.height);
+                    break;
                 case "height":
                 case "height":
-                    this.setSize("",  sz.height);
-                break;
+                    this.setSize(fs.width, sz.height);
+                    break;
+                case "none":
+                    this.setSize(fs.width, fs.height);
+                    break;
                 default:
                 default:
-                    this.setSize(sz.width,  sz.height);
+                    this.setSize(sz.width, sz.height);
             }
         }
     },
             }
         }
     },
@@ -260,9 +283,13 @@ Ext.extend(Ext.Editor, Ext.Component, {
 
     <div id="method-Ext.Editor-realign"></div>/**
      * Realigns the editor to the bound field based on the current alignment config value.
 
     <div id="method-Ext.Editor-realign"></div>/**
      * Realigns the editor to the bound field based on the current alignment config value.
+     * @param {Boolean} autoSize (optional) True to size the field to the dimensions of the bound element.
      */
      */
-    realign : function(){
-        this.el.alignTo(this.boundEl, this.alignment);
+    realign : function(autoSize){
+        if(autoSize === true){
+            this.doAutoSize();
+        }
+        this.el.alignTo(this.boundEl, this.alignment, this.offsets);
     },
 
     <div id="method-Ext.Editor-completeEdit"></div>/**
     },
 
     <div id="method-Ext.Editor-completeEdit"></div>/**
@@ -273,6 +300,10 @@ Ext.extend(Ext.Editor, Ext.Component, {
         if(!this.editing){
             return;
         }
         if(!this.editing){
             return;
         }
+        // Assert combo values first
+        if (this.field.assertValue) {
+            this.field.assertValue();
+        }
         var v = this.getValue();
         if(!this.field.isValid()){
             if(this.revertInvalid !== false){
         var v = this.getValue();
         if(!this.field.isValid()){
             if(this.revertInvalid !== false){
@@ -300,22 +331,10 @@ Ext.extend(Ext.Editor, Ext.Component, {
         if(this.hideEl !== false){
             this.boundEl.hide();
         }
         if(this.hideEl !== false){
             this.boundEl.hide();
         }
-        this.field.show();
-        if(Ext.isIE && !this.fixIEFocus){ // IE has problems with focusing the first time
-            this.fixIEFocus = true;
-            this.deferredFocus.defer(50, this);
-        }else{
-            this.field.focus();
-        }
+        this.field.show().focus(false, true);
         this.fireEvent("startedit", this.boundEl, this.startValue);
     },
 
         this.fireEvent("startedit", this.boundEl, this.startValue);
     },
 
-    deferredFocus : function(){
-        if(this.editing){
-            this.field.focus();
-        }
-    },
-
     <div id="method-Ext.Editor-cancelEdit"></div>/**
      * Cancels the editing process and hides the editor without persisting any changes.  The field value will be
      * reverted to the original starting value.
     <div id="method-Ext.Editor-cancelEdit"></div>/**
      * Cancels the editing process and hides the editor without persisting any changes.  The field value will be
      * reverted to the original starting value.
@@ -330,7 +349,7 @@ Ext.extend(Ext.Editor, Ext.Component, {
             this.fireEvent("canceledit", this, v, this.startValue);
         }
     },
             this.fireEvent("canceledit", this, v, this.startValue);
         }
     },
-    
+
     // private
     hideEdit: function(remainVisible){
         if(remainVisible !== true){
     // private
     hideEdit: function(remainVisible){
         if(remainVisible !== true){
@@ -341,7 +360,8 @@ Ext.extend(Ext.Editor, Ext.Component, {
 
     // private
     onBlur : function(){
 
     // private
     onBlur : function(){
-        if(this.allowBlur !== true && this.editing){
+        // selectSameEditor flag allows the same editor to be started without onBlur firing on itself
+        if(this.allowBlur === true && this.editing && this.selectSameEditor !== true){
             this.completeEdit();
         }
     },
             this.completeEdit();
         }
     },
@@ -379,10 +399,13 @@ Ext.extend(Ext.Editor, Ext.Component, {
     },
 
     beforeDestroy : function(){
     },
 
     beforeDestroy : function(){
-        Ext.destroy(this.field);
-        this.field = null;
+        Ext.destroyMembers(this, 'field');
+
+        delete this.parentEl;
+        delete this.boundEl;
     }
 });
     }
 });
-Ext.reg('editor', Ext.Editor);</pre>    \r
-</body>\r
+Ext.reg('editor', Ext.Editor);
+</pre>    
+</body>
 </html>
\ No newline at end of file
 </html>
\ No newline at end of file