docs/source/Editor.html

   1 <html>\r
   2 <head>\r
   3   <title>The source code</title>\r
   4     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
   5     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
   6 </head>\r
   7 <body  onload="prettyPrint();">\r
   8     <pre class="prettyprint lang-js"><div id="cls-Ext.Editor"></div>/**
   9  * @class Ext.Editor
  10  * @extends Ext.Component
  11  * A base editor field that handles displaying/hiding on demand and has some built-in sizing and event handling logic.
  12  * @constructor
  13  * Create a new Editor
  14  * @param {Object} config The config object
  15  * @xtype editor
  16  */
  17 Ext.Editor = function(field, config){
  18     if(field.field){
  19         this.field = Ext.create(field.field, 'textfield');
  20         config = Ext.apply({}, field); // copy so we don't disturb original config
  21         delete config.field;
  22     }else{
  23         this.field = field;
  24     }
  25     Ext.Editor.superclass.constructor.call(this, config);
  26 };
  27
  28 Ext.extend(Ext.Editor, Ext.Component, {
  29     <div id="cfg-Ext.Editor-field"></div>/**
  30     * @cfg {Ext.form.Field} field
  31     * The Field object (or descendant) or config object for field
  32     */
  33     <div id="cfg-Ext.Editor-allowBlur"></div>/**
  34      * @cfg {Boolean} allowBlur
  35      * True to {@link #completeEdit complete the editing process} if in edit mode when the
  36      * field is blurred. Defaults to <tt>false</tt>.
  37      */
  38     <div id="cfg-Ext.Editor-autoSize"></div>/**
  39      * @cfg {Boolean/String} autoSize
  40      * True for the editor to automatically adopt the size of the element being edited, "width" to adopt the width only,
  41      * or "height" to adopt the height only (defaults to false)
  42      */
  43     <div id="cfg-Ext.Editor-revertInvalid"></div>/**
  44      * @cfg {Boolean} revertInvalid
  45      * True to automatically revert the field value and cancel the edit when the user completes an edit and the field
  46      * validation fails (defaults to true)
  47      */
  48     <div id="cfg-Ext.Editor-ignoreNoChange"></div>/**
  49      * @cfg {Boolean} ignoreNoChange
  50      * True to skip the edit completion process (no save, no events fired) if the user completes an edit and
  51      * the value has not changed (defaults to false).  Applies only to string values - edits for other data types
  52      * will never be ignored.
  53      */
  54     <div id="cfg-Ext.Editor-hideEl"></div>/**
  55      * @cfg {Boolean} hideEl
  56      * False to keep the bound element visible while the editor is displayed (defaults to true)
  57      */
  58     <div id="cfg-Ext.Editor-value"></div>/**
  59      * @cfg {Mixed} value
  60      * The data value of the underlying field (defaults to "")
  61      */
  62     value : "",
  63     <div id="cfg-Ext.Editor-alignment"></div>/**
  64      * @cfg {String} alignment
  65      * The position to align to (see {@link Ext.Element#alignTo} for more details, defaults to "c-c?").
  66      */
  67     alignment: "c-c?",
  68     <div id="cfg-Ext.Editor-shadow"></div>/**
  69      * @cfg {Boolean/String} shadow "sides" for sides/bottom only, "frame" for 4-way shadow, and "drop"
  70      * for bottom-right shadow (defaults to "frame")
  71      */
  72     shadow : "frame",
  73     <div id="cfg-Ext.Editor-constrain"></div>/**
  74      * @cfg {Boolean} constrain True to constrain the editor to the viewport
  75      */
  76     constrain : false,
  77     <div id="cfg-Ext.Editor-swallowKeys"></div>/**
  78      * @cfg {Boolean} swallowKeys Handle the keydown/keypress events so they don't propagate (defaults to true)
  79      */
  80     swallowKeys : true,
  81     <div id="cfg-Ext.Editor-completeOnEnter"></div>/**
  82      * @cfg {Boolean} completeOnEnter True to complete the edit when the enter key is pressed (defaults to false)
  83      */
  84     completeOnEnter : false,
  85     <div id="cfg-Ext.Editor-cancelOnEsc"></div>/**
  86      * @cfg {Boolean} cancelOnEsc True to cancel the edit when the escape key is pressed (defaults to false)
  87      */
  88     cancelOnEsc : false,
  89     <div id="cfg-Ext.Editor-updateEl"></div>/**
  90      * @cfg {Boolean} updateEl True to update the innerHTML of the bound element when the update completes (defaults to false)
  91      */
  92     updateEl : false,
  93
  94     initComponent : function(){
  95         Ext.Editor.superclass.initComponent.call(this);
  96         this.addEvents(
  97             <div id="event-Ext.Editor-beforestartedit"></div>/**
  98              * @event beforestartedit
  99              * Fires when editing is initiated, but before the value changes.  Editing can be canceled by returning
 100              * false from the handler of this event.
 101              * @param {Editor} this
 102              * @param {Ext.Element} boundEl The underlying element bound to this editor
 103              * @param {Mixed} value The field value being set
 104              */
 105             "beforestartedit",
 106             <div id="event-Ext.Editor-startedit"></div>/**
 107              * @event startedit
 108              * Fires when this editor is displayed
 109              * @param {Ext.Element} boundEl The underlying element bound to this editor
 110              * @param {Mixed} value The starting field value
 111              */
 112             "startedit",
 113             <div id="event-Ext.Editor-beforecomplete"></div>/**
 114              * @event beforecomplete
 115              * Fires after a change has been made to the field, but before the change is reflected in the underlying
 116              * field.  Saving the change to the field can be canceled by returning false from the handler of this event.
 117              * Note that if the value has not changed and ignoreNoChange = true, the editing will still end but this
 118              * event will not fire since no edit actually occurred.
 119              * @param {Editor} this
 120              * @param {Mixed} value The current field value
 121              * @param {Mixed} startValue The original field value
 122              */
 123             "beforecomplete",
 124             <div id="event-Ext.Editor-complete"></div>/**
 125              * @event complete
 126              * Fires after editing is complete and any changed value has been written to the underlying field.
 127              * @param {Editor} this
 128              * @param {Mixed} value The current field value
 129              * @param {Mixed} startValue The original field value
 130              */
 131             "complete",
 132             <div id="event-Ext.Editor-canceledit"></div>/**
 133              * @event canceledit
 134              * Fires after editing has been canceled and the editor's value has been reset.
 135              * @param {Editor} this
 136              * @param {Mixed} value The user-entered field value that was discarded
 137              * @param {Mixed} startValue The original field value that was set back into the editor after cancel
 138              */
 139             "canceledit",
 140             <div id="event-Ext.Editor-specialkey"></div>/**
 141              * @event specialkey
 142              * Fires when any key related to navigation (arrows, tab, enter, esc, etc.) is pressed.  You can check
 143              * {@link Ext.EventObject#getKey} to determine which key was pressed.
 144              * @param {Ext.form.Field} this
 145              * @param {Ext.EventObject} e The event object
 146              */
 147             "specialkey"
 148         );
 149     },
 150
 151     // private
 152     onRender : function(ct, position){
 153         this.el = new Ext.Layer({
 154             shadow: this.shadow,
 155             cls: "x-editor",
 156             parentEl : ct,
 157             shim : this.shim,
 158             shadowOffset: this.shadowOffset || 4,
 159             id: this.id,
 160             constrain: this.constrain
 161         });
 162         if(this.zIndex){
 163             this.el.setZIndex(this.zIndex);
 164         }
 165         this.el.setStyle("overflow", Ext.isGecko ? "auto" : "hidden");
 166         if(this.field.msgTarget != 'title'){
 167             this.field.msgTarget = 'qtip';
 168         }
 169         this.field.inEditor = true;
 170         this.field.render(this.el);
 171         if(Ext.isGecko){
 172             this.field.el.dom.setAttribute('autocomplete', 'off');
 173         }
 174         this.mon(this.field, "specialkey", this.onSpecialKey, this);
 175         if(this.swallowKeys){
 176             this.field.el.swallowEvent(['keydown','keypress']);
 177         }
 178         this.field.show();
 179         this.mon(this.field, "blur", this.onBlur, this);
 180         if(this.field.grow){
 181                 this.mon(this.field, "autosize", this.el.sync,  this.el, {delay:1});
 182         }
 183     },
 184
 185     // private
 186     onSpecialKey : function(field, e){
 187         var key = e.getKey();
 188         if(this.completeOnEnter && key == e.ENTER){
 189             e.stopEvent();
 190             this.completeEdit();
 191         }else if(this.cancelOnEsc && key == e.ESC){
 192             this.cancelEdit();
 193         }else{
 194             this.fireEvent('specialkey', field, e);
 195         }
 196         if(this.field.triggerBlur && (key == e.ENTER || key == e.ESC || key == e.TAB)){
 197             this.field.triggerBlur();
 198         }
 199     },
 200
 201     <div id="method-Ext.Editor-startEdit"></div>/**
 202      * Starts the editing process and shows the editor.
 203      * @param {Mixed} el The element to edit
 204      * @param {String} value (optional) A value to initialize the editor with. If a value is not provided, it defaults
 205       * to the innerHTML of el.
 206      */
 207     startEdit : function(el, value){
 208         if(this.editing){
 209             this.completeEdit();
 210         }
 211         this.boundEl = Ext.get(el);
 212         var v = value !== undefined ? value : this.boundEl.dom.innerHTML;
 213         if(!this.rendered){
 214             this.render(this.parentEl || document.body);
 215         }
 216         if(this.fireEvent("beforestartedit", this, this.boundEl, v) === false){
 217             return;
 218         }
 219         this.startValue = v;
 220         this.field.setValue(v);
 221         this.doAutoSize();
 222         this.el.alignTo(this.boundEl, this.alignment);
 223         this.editing = true;
 224         this.show();
 225     },
 226
 227     // private
 228     doAutoSize : function(){
 229         if(this.autoSize){
 230             var sz = this.boundEl.getSize();
 231             switch(this.autoSize){
 232                 case "width":
 233                     this.setSize(sz.width,  "");
 234                 break;
 235                 case "height":
 236                     this.setSize("",  sz.height);
 237                 break;
 238                 default:
 239                     this.setSize(sz.width,  sz.height);
 240             }
 241         }
 242     },
 243
 244     <div id="method-Ext.Editor-setSize"></div>/**
 245      * Sets the height and width of this editor.
 246      * @param {Number} width The new width
 247      * @param {Number} height The new height
 248      */
 249     setSize : function(w, h){
 250         delete this.field.lastSize;
 251         this.field.setSize(w, h);
 252         if(this.el){
 253             if(Ext.isGecko2 || Ext.isOpera){
 254                 // prevent layer scrollbars
 255                 this.el.setSize(w, h);
 256             }
 257             this.el.sync();
 258         }
 259     },
 260
 261     <div id="method-Ext.Editor-realign"></div>/**
 262      * Realigns the editor to the bound field based on the current alignment config value.
 263      */
 264     realign : function(){
 265         this.el.alignTo(this.boundEl, this.alignment);
 266     },
 267
 268     <div id="method-Ext.Editor-completeEdit"></div>/**
 269      * Ends the editing process, persists the changed value to the underlying field, and hides the editor.
 270      * @param {Boolean} remainVisible Override the default behavior and keep the editor visible after edit (defaults to false)
 271      */
 272     completeEdit : function(remainVisible){
 273         if(!this.editing){
 274             return;
 275         }
 276         var v = this.getValue();
 277         if(!this.field.isValid()){
 278             if(this.revertInvalid !== false){
 279                 this.cancelEdit(remainVisible);
 280             }
 281             return;
 282         }
 283         if(String(v) === String(this.startValue) && this.ignoreNoChange){
 284             this.hideEdit(remainVisible);
 285             return;
 286         }
 287         if(this.fireEvent("beforecomplete", this, v, this.startValue) !== false){
 288             v = this.getValue();
 289             if(this.updateEl && this.boundEl){
 290                 this.boundEl.update(v);
 291             }
 292             this.hideEdit(remainVisible);
 293             this.fireEvent("complete", this, v, this.startValue);
 294         }
 295     },
 296
 297     // private
 298     onShow : function(){
 299         this.el.show();
 300         if(this.hideEl !== false){
 301             this.boundEl.hide();
 302         }
 303         this.field.show();
 304         if(Ext.isIE && !this.fixIEFocus){ // IE has problems with focusing the first time
 305             this.fixIEFocus = true;
 306             this.deferredFocus.defer(50, this);
 307         }else{
 308             this.field.focus();
 309         }
 310         this.fireEvent("startedit", this.boundEl, this.startValue);
 311     },
 312
 313     deferredFocus : function(){
 314         if(this.editing){
 315             this.field.focus();
 316         }
 317     },
 318
 319     <div id="method-Ext.Editor-cancelEdit"></div>/**
 320      * Cancels the editing process and hides the editor without persisting any changes.  The field value will be
 321      * reverted to the original starting value.
 322      * @param {Boolean} remainVisible Override the default behavior and keep the editor visible after
 323      * cancel (defaults to false)
 324      */
 325     cancelEdit : function(remainVisible){
 326         if(this.editing){
 327             var v = this.getValue();
 328             this.setValue(this.startValue);
 329             this.hideEdit(remainVisible);
 330             this.fireEvent("canceledit", this, v, this.startValue);
 331         }
 332     },
 333
 334     // private
 335     hideEdit: function(remainVisible){
 336         if(remainVisible !== true){
 337             this.editing = false;
 338             this.hide();
 339         }
 340     },
 341
 342     // private
 343     onBlur : function(){
 344         if(this.allowBlur !== true && this.editing){
 345             this.completeEdit();
 346         }
 347     },
 348
 349     // private
 350     onHide : function(){
 351         if(this.editing){
 352             this.completeEdit();
 353             return;
 354         }
 355         this.field.blur();
 356         if(this.field.collapse){
 357             this.field.collapse();
 358         }
 359         this.el.hide();
 360         if(this.hideEl !== false){
 361             this.boundEl.show();
 362         }
 363     },
 364
 365     <div id="method-Ext.Editor-setValue"></div>/**
 366      * Sets the data value of the editor
 367      * @param {Mixed} value Any valid value supported by the underlying field
 368      */
 369     setValue : function(v){
 370         this.field.setValue(v);
 371     },
 372
 373     <div id="method-Ext.Editor-getValue"></div>/**
 374      * Gets the data value of the editor
 375      * @return {Mixed} The data value
 376      */
 377     getValue : function(){
 378         return this.field.getValue();
 379     },
 380
 381     beforeDestroy : function(){
 382         Ext.destroy(this.field);
 383         this.field = null;
 384     }
 385 });
 386 Ext.reg('editor', Ext.Editor);</pre>    \r
 387 </body>\r
 388 </html>