docs/source/TriggerField.html

   1 <html>
   2 <head>
   3   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   4   <title>The source code</title>
   5     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
   6     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
   7 </head>
   8 <body  onload="prettyPrint();">
   9     <pre class="prettyprint lang-js">/*!
  10  * Ext JS Library 3.3.1
  11  * Copyright(c) 2006-2010 Sencha Inc.
  12  * licensing@sencha.com
  13  * http://www.sencha.com/license
  14  */
  15 <div id="cls-Ext.form.TriggerField"></div>/**
  16  * @class Ext.form.TriggerField
  17  * @extends Ext.form.TextField
  18  * Provides a convenient wrapper for TextFields that adds a clickable trigger button (looks like a combobox by default).
  19  * The trigger has no default action, so you must assign a function to implement the trigger click handler by
  20  * overriding {@link #onTriggerClick}. You can create a TriggerField directly, as it renders exactly like a combobox
  21  * for which you can provide a custom implementation.  For example:
  22  * <pre><code>
  23 var trigger = new Ext.form.TriggerField();
  24 trigger.onTriggerClick = myTriggerFn;
  25 trigger.applyToMarkup('my-field');
  26 </code></pre>
  27  *
  28  * However, in general you will most likely want to use TriggerField as the base class for a reusable component.
  29  * {@link Ext.form.DateField} and {@link Ext.form.ComboBox} are perfect examples of this.
  30  *
  31  * @constructor
  32  * Create a new TriggerField.
  33  * @param {Object} config Configuration options (valid {@Ext.form.TextField} config options will also be applied
  34  * to the base TextField)
  35  * @xtype trigger
  36  */
  37 Ext.form.TriggerField = Ext.extend(Ext.form.TextField,  {
  38     <div id="cfg-Ext.form.TriggerField-triggerClass"></div>/**
  39      * @cfg {String} triggerClass
  40      * An additional CSS class used to style the trigger button.  The trigger will always get the
  41      * class <tt>'x-form-trigger'</tt> by default and <tt>triggerClass</tt> will be <b>appended</b> if specified.
  42      */
  43     <div id="cfg-Ext.form.TriggerField-triggerConfig"></div>/**
  44      * @cfg {Mixed} triggerConfig
  45      * <p>A {@link Ext.DomHelper DomHelper} config object specifying the structure of the
  46      * trigger element for this Field. (Optional).</p>
  47      * <p>Specify this when you need a customized element to act as the trigger button for a TriggerField.</p>
  48      * <p>Note that when using this option, it is the developer's responsibility to ensure correct sizing, positioning
  49      * and appearance of the trigger.  Defaults to:</p>
  50      * <pre><code>{tag: "img", src: Ext.BLANK_IMAGE_URL, cls: "x-form-trigger " + this.triggerClass}</code></pre>
  51      */
  52     <div id="cfg-Ext.form.TriggerField-autoCreate"></div>/**
  53      * @cfg {String/Object} autoCreate <p>A {@link Ext.DomHelper DomHelper} element spec, or true for a default
  54      * element spec. Used to create the {@link Ext.Component#getEl Element} which will encapsulate this Component.
  55      * See <tt>{@link Ext.Component#autoEl autoEl}</tt> for details.  Defaults to:</p>
  56      * <pre><code>{tag: "input", type: "text", size: "16", autocomplete: "off"}</code></pre>
  57      */
  58     defaultAutoCreate : {tag: "input", type: "text", size: "16", autocomplete: "off"},
  59     <div id="cfg-Ext.form.TriggerField-hideTrigger"></div>/**
  60      * @cfg {Boolean} hideTrigger <tt>true</tt> to hide the trigger element and display only the base
  61      * text field (defaults to <tt>false</tt>)
  62      */
  63     hideTrigger:false,
  64     <div id="cfg-Ext.form.TriggerField-editable"></div>/**
  65      * @cfg {Boolean} editable <tt>false</tt> to prevent the user from typing text directly into the field,
  66      * the field will only respond to a click on the trigger to set the value. (defaults to <tt>true</tt>).
  67      */
  68     editable: true,
  69     <div id="cfg-Ext.form.TriggerField-readOnly"></div>/**
  70      * @cfg {Boolean} readOnly <tt>true</tt> to prevent the user from changing the field, and
  71      * hides the trigger.  Superceeds the editable and hideTrigger options if the value is true.
  72      * (defaults to <tt>false</tt>)
  73      */
  74     readOnly: false,
  75     <div id="cfg-Ext.form.TriggerField-wrapFocusClass"></div>/**
  76      * @cfg {String} wrapFocusClass The class added to the to the wrap of the trigger element. Defaults to
  77      * <tt>x-trigger-wrap-focus</tt>.
  78      */
  79     wrapFocusClass: 'x-trigger-wrap-focus',
  80     <div id="method-Ext.form.TriggerField-autoSize"></div>/**
  81      * @hide
  82      * @method autoSize
  83      */
  84     autoSize: Ext.emptyFn,
  85     // private
  86     monitorTab : true,
  87     // private
  88     deferHeight : true,
  89     // private
  90     mimicing : false,
  91
  92     actionMode: 'wrap',
  93
  94     defaultTriggerWidth: 17,
  95
  96     // private
  97     onResize : function(w, h){
  98         Ext.form.TriggerField.superclass.onResize.call(this, w, h);
  99         var tw = this.getTriggerWidth();
 100         if(Ext.isNumber(w)){
 101             this.el.setWidth(w - tw);
 102         }
 103         this.wrap.setWidth(this.el.getWidth() + tw);
 104     },
 105
 106     getTriggerWidth: function(){
 107         var tw = this.trigger.getWidth();
 108         if(!this.hideTrigger && !this.readOnly && tw === 0){
 109             tw = this.defaultTriggerWidth;
 110         }
 111         return tw;
 112     },
 113
 114     // private
 115     alignErrorIcon : function(){
 116         if(this.wrap){
 117             this.errorIcon.alignTo(this.wrap, 'tl-tr', [2, 0]);
 118         }
 119     },
 120
 121     // private
 122     onRender : function(ct, position){
 123         this.doc = Ext.isIE ? Ext.getBody() : Ext.getDoc();
 124         Ext.form.TriggerField.superclass.onRender.call(this, ct, position);
 125
 126         this.wrap = this.el.wrap({cls: 'x-form-field-wrap x-form-field-trigger-wrap'});
 127         this.trigger = this.wrap.createChild(this.triggerConfig ||
 128                 {tag: "img", src: Ext.BLANK_IMAGE_URL, alt: "", cls: "x-form-trigger " + this.triggerClass});
 129         this.initTrigger();
 130         if(!this.width){
 131             this.wrap.setWidth(this.el.getWidth()+this.trigger.getWidth());
 132         }
 133         this.resizeEl = this.positionEl = this.wrap;
 134     },
 135
 136     getWidth: function() {
 137         return(this.el.getWidth() + this.trigger.getWidth());
 138     },
 139
 140     updateEditState: function(){
 141         if(this.rendered){
 142             if (this.readOnly) {
 143                 this.el.dom.readOnly = true;
 144                 this.el.addClass('x-trigger-noedit');
 145                 this.mun(this.el, 'click', this.onTriggerClick, this);
 146                 this.trigger.setDisplayed(false);
 147             } else {
 148                 if (!this.editable) {
 149                     this.el.dom.readOnly = true;
 150                     this.el.addClass('x-trigger-noedit');
 151                     this.mon(this.el, 'click', this.onTriggerClick, this);
 152                 } else {
 153                     this.el.dom.readOnly = false;
 154                     this.el.removeClass('x-trigger-noedit');
 155                     this.mun(this.el, 'click', this.onTriggerClick, this);
 156                 }
 157                 this.trigger.setDisplayed(!this.hideTrigger);
 158             }
 159             this.onResize(this.width || this.wrap.getWidth());
 160         }
 161     },
 162
 163     <div id="method-Ext.form.TriggerField-setHideTrigger"></div>/**
 164      * Changes the hidden status of the trigger.
 165      * @param {Boolean} hideTrigger True to hide the trigger, false to show it.
 166      */
 167     setHideTrigger: function(hideTrigger){
 168         if(hideTrigger != this.hideTrigger){
 169             this.hideTrigger = hideTrigger;
 170             this.updateEditState();
 171         }
 172     },
 173
 174     <div id="method-Ext.form.TriggerField-setEditable"></div>/**
 175      * Allow or prevent the user from directly editing the field text.  If false is passed,
 176      * the user will only be able to modify the field using the trigger.  Will also add
 177      * a click event to the text field which will call the trigger. This method
 178      * is the runtime equivalent of setting the {@link #editable} config option at config time.
 179      * @param {Boolean} value True to allow the user to directly edit the field text.
 180      */
 181     setEditable: function(editable){
 182         if(editable != this.editable){
 183             this.editable = editable;
 184             this.updateEditState();
 185         }
 186     },
 187
 188     <div id="method-Ext.form.TriggerField-setReadOnly"></div>/**
 189      * Setting this to true will supersede settings {@link #editable} and {@link #hideTrigger}.
 190      * Setting this to false will defer back to {@link #editable} and {@link #hideTrigger}. This method
 191      * is the runtime equivalent of setting the {@link #readOnly} config option at config time.
 192      * @param {Boolean} value True to prevent the user changing the field and explicitly
 193      * hide the trigger.
 194      */
 195     setReadOnly: function(readOnly){
 196         if(readOnly != this.readOnly){
 197             this.readOnly = readOnly;
 198             this.updateEditState();
 199         }
 200     },
 201
 202     afterRender : function(){
 203         Ext.form.TriggerField.superclass.afterRender.call(this);
 204         this.updateEditState();
 205     },
 206
 207     // private
 208     initTrigger : function(){
 209         this.mon(this.trigger, 'click', this.onTriggerClick, this, {preventDefault:true});
 210         this.trigger.addClassOnOver('x-form-trigger-over');
 211         this.trigger.addClassOnClick('x-form-trigger-click');
 212     },
 213
 214     // private
 215     onDestroy : function(){
 216         Ext.destroy(this.trigger, this.wrap);
 217         if (this.mimicing){
 218             this.doc.un('mousedown', this.mimicBlur, this);
 219         }
 220         delete this.doc;
 221         Ext.form.TriggerField.superclass.onDestroy.call(this);
 222     },
 223
 224     // private
 225     onFocus : function(){
 226         Ext.form.TriggerField.superclass.onFocus.call(this);
 227         if(!this.mimicing){
 228             this.wrap.addClass(this.wrapFocusClass);
 229             this.mimicing = true;
 230             this.doc.on('mousedown', this.mimicBlur, this, {delay: 10});
 231             if(this.monitorTab){
 232                 this.on('specialkey', this.checkTab, this);
 233             }
 234         }
 235     },
 236
 237     // private
 238     checkTab : function(me, e){
 239         if(e.getKey() == e.TAB){
 240             this.triggerBlur();
 241         }
 242     },
 243
 244     // private
 245     onBlur : Ext.emptyFn,
 246
 247     // private
 248     mimicBlur : function(e){
 249         if(!this.isDestroyed && !this.wrap.contains(e.target) && this.validateBlur(e)){
 250             this.triggerBlur();
 251         }
 252     },
 253
 254     // private
 255     triggerBlur : function(){
 256         this.mimicing = false;
 257         this.doc.un('mousedown', this.mimicBlur, this);
 258         if(this.monitorTab && this.el){
 259             this.un('specialkey', this.checkTab, this);
 260         }
 261         Ext.form.TriggerField.superclass.onBlur.call(this);
 262         if(this.wrap){
 263             this.wrap.removeClass(this.wrapFocusClass);
 264         }
 265     },
 266
 267     beforeBlur : Ext.emptyFn,
 268
 269     // private
 270     // This should be overriden by any subclass that needs to check whether or not the field can be blurred.
 271     validateBlur : function(e){
 272         return true;
 273     },
 274
 275     <div id="method-Ext.form.TriggerField-onTriggerClick"></div>/**
 276      * The function that should handle the trigger's click event.  This method does nothing by default
 277      * until overridden by an implementing function.  See Ext.form.ComboBox and Ext.form.DateField for
 278      * sample implementations.
 279      * @method
 280      * @param {EventObject} e
 281      */
 282     onTriggerClick : Ext.emptyFn
 283
 284     <div id="cfg-Ext.form.TriggerField-grow"></div>/**
 285      * @cfg {Boolean} grow @hide
 286      */
 287     <div id="cfg-Ext.form.TriggerField-growMin"></div>/**
 288      * @cfg {Number} growMin @hide
 289      */
 290     <div id="cfg-Ext.form.TriggerField-growMax"></div>/**
 291      * @cfg {Number} growMax @hide
 292      */
 293 });
 294
 295 <div id="cls-Ext.form.TwinTriggerField"></div>/**
 296  * @class Ext.form.TwinTriggerField
 297  * @extends Ext.form.TriggerField
 298  * TwinTriggerField is not a public class to be used directly.  It is meant as an abstract base class
 299  * to be extended by an implementing class.  For an example of implementing this class, see the custom
 300  * SearchField implementation here:
 301  * <a href="http://extjs.com/deploy/ext/examples/form/custom.html">http://extjs.com/deploy/ext/examples/form/custom.html</a>
 302  */
 303 Ext.form.TwinTriggerField = Ext.extend(Ext.form.TriggerField, {
 304     <div id="cfg-Ext.form.TwinTriggerField-triggerConfig"></div>/**
 305      * @cfg {Mixed} triggerConfig
 306      * <p>A {@link Ext.DomHelper DomHelper} config object specifying the structure of the trigger elements
 307      * for this Field. (Optional).</p>
 308      * <p>Specify this when you need a customized element to contain the two trigger elements for this Field.
 309      * Each trigger element must be marked by the CSS class <tt>x-form-trigger</tt> (also see
 310      * <tt>{@link #trigger1Class}</tt> and <tt>{@link #trigger2Class}</tt>).</p>
 311      * <p>Note that when using this option, it is the developer's responsibility to ensure correct sizing,
 312      * positioning and appearance of the triggers.</p>
 313      */
 314     <div id="cfg-Ext.form.TwinTriggerField-trigger1Class"></div>/**
 315      * @cfg {String} trigger1Class
 316      * An additional CSS class used to style the trigger button.  The trigger will always get the
 317      * class <tt>'x-form-trigger'</tt> by default and <tt>triggerClass</tt> will be <b>appended</b> if specified.
 318      */
 319     <div id="cfg-Ext.form.TwinTriggerField-trigger2Class"></div>/**
 320      * @cfg {String} trigger2Class
 321      * An additional CSS class used to style the trigger button.  The trigger will always get the
 322      * class <tt>'x-form-trigger'</tt> by default and <tt>triggerClass</tt> will be <b>appended</b> if specified.
 323      */
 324
 325     initComponent : function(){
 326         Ext.form.TwinTriggerField.superclass.initComponent.call(this);
 327
 328         this.triggerConfig = {
 329             tag:'span', cls:'x-form-twin-triggers', cn:[
 330             {tag: "img", src: Ext.BLANK_IMAGE_URL, alt: "", cls: "x-form-trigger " + this.trigger1Class},
 331             {tag: "img", src: Ext.BLANK_IMAGE_URL, alt: "", cls: "x-form-trigger " + this.trigger2Class}
 332         ]};
 333     },
 334
 335     getTrigger : function(index){
 336         return this.triggers[index];
 337     },
 338
 339     afterRender: function(){
 340         Ext.form.TwinTriggerField.superclass.afterRender.call(this);
 341         var triggers = this.triggers,
 342             i = 0,
 343             len = triggers.length;
 344
 345         for(; i < len; ++i){
 346             if(this['hideTrigger' + (i + 1)]){
 347                     triggers[i].hide();
 348                 }
 349
 350         }
 351     },
 352
 353     initTrigger : function(){
 354         var ts = this.trigger.select('.x-form-trigger', true),
 355             triggerField = this;
 356
 357         ts.each(function(t, all, index){
 358             var triggerIndex = 'Trigger'+(index+1);
 359             t.hide = function(){
 360                 var w = triggerField.wrap.getWidth();
 361                 this.dom.style.display = 'none';
 362                 triggerField.el.setWidth(w-triggerField.trigger.getWidth());
 363                 triggerField['hidden' + triggerIndex] = true;
 364             };
 365             t.show = function(){
 366                 var w = triggerField.wrap.getWidth();
 367                 this.dom.style.display = '';
 368                 triggerField.el.setWidth(w-triggerField.trigger.getWidth());
 369                 triggerField['hidden' + triggerIndex] = false;
 370             };
 371             this.mon(t, 'click', this['on'+triggerIndex+'Click'], this, {preventDefault:true});
 372             t.addClassOnOver('x-form-trigger-over');
 373             t.addClassOnClick('x-form-trigger-click');
 374         }, this);
 375         this.triggers = ts.elements;
 376     },
 377
 378     getTriggerWidth: function(){
 379         var tw = 0;
 380         Ext.each(this.triggers, function(t, index){
 381             var triggerIndex = 'Trigger' + (index + 1),
 382                 w = t.getWidth();
 383             if(w === 0 && !this['hidden' + triggerIndex]){
 384                 tw += this.defaultTriggerWidth;
 385             }else{
 386                 tw += w;
 387             }
 388         }, this);
 389         return tw;
 390     },
 391
 392     // private
 393     onDestroy : function() {
 394         Ext.destroy(this.triggers);
 395         Ext.form.TwinTriggerField.superclass.onDestroy.call(this);
 396     },
 397
 398     <div id="method-Ext.form.TwinTriggerField-onTrigger1Click"></div>/**
 399      * The function that should handle the trigger's click event.  This method does nothing by default
 400      * until overridden by an implementing function. See {@link Ext.form.TriggerField#onTriggerClick}
 401      * for additional information.
 402      * @method
 403      * @param {EventObject} e
 404      */
 405     onTrigger1Click : Ext.emptyFn,
 406     <div id="method-Ext.form.TwinTriggerField-onTrigger2Click"></div>/**
 407      * The function that should handle the trigger's click event.  This method does nothing by default
 408      * until overridden by an implementing function. See {@link Ext.form.TriggerField#onTriggerClick}
 409      * for additional information.
 410      * @method
 411      * @param {EventObject} e
 412      */
 413     onTrigger2Click : Ext.emptyFn
 414 });
 415 Ext.reg('trigger', Ext.form.TriggerField);
 416 </pre>
 417 </body>
 418 </html>