Upgrade to ExtJS 3.2.1 - Released 04/27/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.2.1
11  * Copyright(c) 2006-2010 Ext JS, Inc.
12  * licensing@extjs.com
13  * http://www.extjs.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, 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     setHideTrigger: function(hideTrigger){
164         if(hideTrigger != this.hideTrigger){
165             this.hideTrigger = hideTrigger;
166             this.updateEditState();
167         }
168     },
169
170     <div id="method-Ext.form.TriggerField-setEditable"></div>/**
171      * @param {Boolean} value True to allow the user to directly edit the field text
172      * Allow or prevent the user from directly editing the field text.  If false is passed,
173      * the user will only be able to modify the field using the trigger.  Will also add
174      * a click event to the text field which will call the trigger. This method
175      * is the runtime equivalent of setting the 'editable' config option at config time.
176      */
177     setEditable: function(editable){
178         if(editable != this.editable){
179             this.editable = editable;
180             this.updateEditState();
181         }
182     },
183
184     <div id="method-Ext.form.TriggerField-setReadOnly"></div>/**
185      * @param {Boolean} value True to prevent the user changing the field and explicitly
186      * hide the trigger.
187      * Setting this to true will superceed settings editable and hideTrigger.
188      * Setting this to false will defer back to editable and hideTrigger. This method
189      * is the runtime equivalent of setting the 'readOnly' config option at config time.
190      */
191     setReadOnly: function(readOnly){
192         if(readOnly != this.readOnly){
193             this.readOnly = readOnly;
194             this.updateEditState();
195         }
196     },
197
198     afterRender : function(){
199         Ext.form.TriggerField.superclass.afterRender.call(this);
200         this.updateEditState();
201     },
202
203     // private
204     initTrigger : function(){
205         this.mon(this.trigger, 'click', this.onTriggerClick, this, {preventDefault:true});
206         this.trigger.addClassOnOver('x-form-trigger-over');
207         this.trigger.addClassOnClick('x-form-trigger-click');
208     },
209
210     // private
211     onDestroy : function(){
212         Ext.destroy(this.trigger, this.wrap);
213         if (this.mimicing){
214             this.doc.un('mousedown', this.mimicBlur, this);
215         }
216         delete this.doc;
217         Ext.form.TriggerField.superclass.onDestroy.call(this);
218     },
219
220     // private
221     onFocus : function(){
222         Ext.form.TriggerField.superclass.onFocus.call(this);
223         if(!this.mimicing){
224             this.wrap.addClass(this.wrapFocusClass);
225             this.mimicing = true;
226             this.doc.on('mousedown', this.mimicBlur, this, {delay: 10});
227             if(this.monitorTab){
228                 this.on('specialkey', this.checkTab, this);
229             }
230         }
231     },
232
233     // private
234     checkTab : function(me, e){
235         if(e.getKey() == e.TAB){
236             this.triggerBlur();
237         }
238     },
239
240     // private
241     onBlur : Ext.emptyFn,
242
243     // private
244     mimicBlur : function(e){
245         if(!this.isDestroyed && !this.wrap.contains(e.target) && this.validateBlur(e)){
246             this.triggerBlur();
247         }
248     },
249
250     // private
251     triggerBlur : function(){
252         this.mimicing = false;
253         this.doc.un('mousedown', this.mimicBlur, this);
254         if(this.monitorTab && this.el){
255             this.un('specialkey', this.checkTab, this);
256         }
257         Ext.form.TriggerField.superclass.onBlur.call(this);
258         if(this.wrap){
259             this.wrap.removeClass(this.wrapFocusClass);
260         }
261     },
262
263     beforeBlur : Ext.emptyFn,
264
265     // private
266     // This should be overriden by any subclass that needs to check whether or not the field can be blurred.
267     validateBlur : function(e){
268         return true;
269     },
270
271     <div id="method-Ext.form.TriggerField-onTriggerClick"></div>/**
272      * The function that should handle the trigger's click event.  This method does nothing by default
273      * until overridden by an implementing function.  See Ext.form.ComboBox and Ext.form.DateField for
274      * sample implementations.
275      * @method
276      * @param {EventObject} e
277      */
278     onTriggerClick : Ext.emptyFn
279
280     <div id="cfg-Ext.form.TriggerField-grow"></div>/**
281      * @cfg {Boolean} grow @hide
282      */
283     <div id="cfg-Ext.form.TriggerField-growMin"></div>/**
284      * @cfg {Number} growMin @hide
285      */
286     <div id="cfg-Ext.form.TriggerField-growMax"></div>/**
287      * @cfg {Number} growMax @hide
288      */
289 });
290
291 <div id="cls-Ext.form.TwinTriggerField"></div>/**
292  * @class Ext.form.TwinTriggerField
293  * @extends Ext.form.TriggerField
294  * TwinTriggerField is not a public class to be used directly.  It is meant as an abstract base class
295  * to be extended by an implementing class.  For an example of implementing this class, see the custom
296  * SearchField implementation here:
297  * <a href="http://extjs.com/deploy/ext/examples/form/custom.html">http://extjs.com/deploy/ext/examples/form/custom.html</a>
298  */
299 Ext.form.TwinTriggerField = Ext.extend(Ext.form.TriggerField, {
300     <div id="cfg-Ext.form.TwinTriggerField-triggerConfig"></div>/**
301      * @cfg {Mixed} triggerConfig
302      * <p>A {@link Ext.DomHelper DomHelper} config object specifying the structure of the trigger elements
303      * for this Field. (Optional).</p>
304      * <p>Specify this when you need a customized element to contain the two trigger elements for this Field.
305      * Each trigger element must be marked by the CSS class <tt>x-form-trigger</tt> (also see
306      * <tt>{@link #trigger1Class}</tt> and <tt>{@link #trigger2Class}</tt>).</p>
307      * <p>Note that when using this option, it is the developer's responsibility to ensure correct sizing,
308      * positioning and appearance of the triggers.</p>
309      */
310     <div id="cfg-Ext.form.TwinTriggerField-trigger1Class"></div>/**
311      * @cfg {String} trigger1Class
312      * An additional CSS class used to style the trigger button.  The trigger will always get the
313      * class <tt>'x-form-trigger'</tt> by default and <tt>triggerClass</tt> will be <b>appended</b> if specified.
314      */
315     <div id="cfg-Ext.form.TwinTriggerField-trigger2Class"></div>/**
316      * @cfg {String} trigger2Class
317      * An additional CSS class used to style the trigger button.  The trigger will always get the
318      * class <tt>'x-form-trigger'</tt> by default and <tt>triggerClass</tt> will be <b>appended</b> if specified.
319      */
320
321     initComponent : function(){
322         Ext.form.TwinTriggerField.superclass.initComponent.call(this);
323
324         this.triggerConfig = {
325             tag:'span', cls:'x-form-twin-triggers', cn:[
326             {tag: "img", src: Ext.BLANK_IMAGE_URL, cls: "x-form-trigger " + this.trigger1Class},
327             {tag: "img", src: Ext.BLANK_IMAGE_URL, cls: "x-form-trigger " + this.trigger2Class}
328         ]};
329     },
330
331     getTrigger : function(index){
332         return this.triggers[index];
333     },
334
335     initTrigger : function(){
336         var ts = this.trigger.select('.x-form-trigger', true);
337         var triggerField = this;
338         ts.each(function(t, all, index){
339             var triggerIndex = 'Trigger'+(index+1);
340             t.hide = function(){
341                 var w = triggerField.wrap.getWidth();
342                 this.dom.style.display = 'none';
343                 triggerField.el.setWidth(w-triggerField.trigger.getWidth());
344                 this['hidden' + triggerIndex] = true;
345             };
346             t.show = function(){
347                 var w = triggerField.wrap.getWidth();
348                 this.dom.style.display = '';
349                 triggerField.el.setWidth(w-triggerField.trigger.getWidth());
350                 this['hidden' + triggerIndex] = false;
351             };
352
353             if(this['hide'+triggerIndex]){
354                 t.dom.style.display = 'none';
355                 this['hidden' + triggerIndex] = true;
356             }
357             this.mon(t, 'click', this['on'+triggerIndex+'Click'], this, {preventDefault:true});
358             t.addClassOnOver('x-form-trigger-over');
359             t.addClassOnClick('x-form-trigger-click');
360         }, this);
361         this.triggers = ts.elements;
362     },
363
364     getTriggerWidth: function(){
365         var tw = 0;
366         Ext.each(this.triggers, function(t, index){
367             var triggerIndex = 'Trigger' + (index + 1),
368                 w = t.getWidth();
369             if(w === 0 && !this['hidden' + triggerIndex]){
370                 tw += this.defaultTriggerWidth;
371             }else{
372                 tw += w;
373             }
374         }, this);
375         return tw;
376     },
377
378     // private
379     onDestroy : function() {
380         Ext.destroy(this.triggers);
381         Ext.form.TwinTriggerField.superclass.onDestroy.call(this);
382     },
383
384     <div id="method-Ext.form.TwinTriggerField-onTrigger1Click"></div>/**
385      * The function that should handle the trigger's click event.  This method does nothing by default
386      * until overridden by an implementing function. See {@link Ext.form.TriggerField#onTriggerClick}
387      * for additional information.
388      * @method
389      * @param {EventObject} e
390      */
391     onTrigger1Click : Ext.emptyFn,
392     <div id="method-Ext.form.TwinTriggerField-onTrigger2Click"></div>/**
393      * The function that should handle the trigger's click event.  This method does nothing by default
394      * until overridden by an implementing function. See {@link Ext.form.TriggerField#onTriggerClick}
395      * for additional information.
396      * @method
397      * @param {EventObject} e
398      */
399     onTrigger2Click : Ext.emptyFn
400 });
401 Ext.reg('trigger', Ext.form.TriggerField);
402 </pre>    
403 </body>
404 </html>