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