Upgrade to ExtJS 3.3.1 - Released 11/30/2010
[extjs.git] / 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>