Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / Number2.html
1 <!DOCTYPE html>
2 <html>
3 <head>
4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5   <title>The source code</title>
6   <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
7   <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
8   <style type="text/css">
9     .highlight { display: block; background-color: #ddd; }
10   </style>
11   <script type="text/javascript">
12     function highlight() {
13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
14     }
15   </script>
16 </head>
17 <body onload="prettyPrint(); highlight();">
18   <pre class="prettyprint lang-js"><span id='Ext-form-field-Number'>/**
19 </span> * @docauthor Jason Johnston &lt;jason@sencha.com&gt;
20  *
21  * A numeric text field that provides automatic keystroke filtering to disallow non-numeric characters,
22  * and numeric validation to limit the value to a range of valid numbers. The range of acceptable number
23  * values can be controlled by setting the {@link #minValue} and {@link #maxValue} configs, and fractional
24  * decimals can be disallowed by setting {@link #allowDecimals} to `false`.
25  *
26  * By default, the number field is also rendered with a set of up/down spinner buttons and has
27  * up/down arrow key and mouse wheel event listeners attached for incrementing/decrementing the value by the
28  * {@link #step} value. To hide the spinner buttons set `{@link #hideTrigger hideTrigger}:true`; to disable
29  * the arrow key and mouse wheel handlers set `{@link #keyNavEnabled keyNavEnabled}:false` and
30  * `{@link #mouseWheelEnabled mouseWheelEnabled}:false`. See the example below.
31  *
32  * # Example usage
33  *
34  *     @example
35  *     Ext.create('Ext.form.Panel', {
36  *         title: 'On The Wall',
37  *         width: 300,
38  *         bodyPadding: 10,
39  *         renderTo: Ext.getBody(),
40  *         items: [{
41  *             xtype: 'numberfield',
42  *             anchor: '100%',
43  *             name: 'bottles',
44  *             fieldLabel: 'Bottles of Beer',
45  *             value: 99,
46  *             maxValue: 99,
47  *             minValue: 0
48  *         }],
49  *         buttons: [{
50  *             text: 'Take one down, pass it around',
51  *             handler: function() {
52  *                 this.up('form').down('[name=bottles]').spinDown();
53  *             }
54  *         }]
55  *     });
56  *
57  * # Removing UI Enhancements
58  *
59  *     @example
60  *     Ext.create('Ext.form.Panel', {
61  *         title: 'Personal Info',
62  *         width: 300,
63  *         bodyPadding: 10,
64  *         renderTo: Ext.getBody(),
65  *         items: [{
66  *             xtype: 'numberfield',
67  *             anchor: '100%',
68  *             name: 'age',
69  *             fieldLabel: 'Age',
70  *             minValue: 0, //prevents negative numbers
71  *
72  *             // Remove spinner buttons, and arrow key and mouse wheel listeners
73  *             hideTrigger: true,
74  *             keyNavEnabled: false,
75  *             mouseWheelEnabled: false
76  *         }]
77  *     });
78  *
79  * # Using Step
80  *
81  *     @example
82  *     Ext.create('Ext.form.Panel', {
83  *         renderTo: Ext.getBody(),
84  *         title: 'Step',
85  *         width: 300,
86  *         bodyPadding: 10,
87  *         items: [{
88  *             xtype: 'numberfield',
89  *             anchor: '100%',
90  *             name: 'evens',
91  *             fieldLabel: 'Even Numbers',
92  *
93  *             // Set step so it skips every other number
94  *             step: 2,
95  *             value: 0,
96  *
97  *             // Add change handler to force user-entered numbers to evens
98  *             listeners: {
99  *                 change: function(field, value) {
100  *                     value = parseInt(value, 10);
101  *                     field.setValue(value + value % 2);
102  *                 }
103  *             }
104  *         }]
105  *     });
106  */
107 Ext.define('Ext.form.field.Number', {
108     extend:'Ext.form.field.Spinner',
109     alias: 'widget.numberfield',
110     alternateClassName: ['Ext.form.NumberField', 'Ext.form.Number'],
111
112 <span id='Ext-form-field-Number-cfg-stripCharsRe'>    /**
113 </span>     * @cfg {RegExp} stripCharsRe @hide
114      */
115 <span id='Ext-form-field-Number-cfg-maskRe'>    /**
116 </span>     * @cfg {RegExp} maskRe @hide
117      */
118
119 <span id='Ext-form-field-Number-cfg-allowDecimals'>    /**
120 </span>     * @cfg {Boolean} allowDecimals
121      * False to disallow decimal values
122      */
123     allowDecimals : true,
124
125 <span id='Ext-form-field-Number-cfg-decimalSeparator'>    /**
126 </span>     * @cfg {String} decimalSeparator
127      * Character(s) to allow as the decimal separator
128      */
129     decimalSeparator : '.',
130
131 <span id='Ext-form-field-Number-cfg-decimalPrecision'>    /**
132 </span>     * @cfg {Number} decimalPrecision
133      * The maximum precision to display after the decimal separator
134      */
135     decimalPrecision : 2,
136
137 <span id='Ext-form-field-Number-cfg-minValue'>    /**
138 </span>     * @cfg {Number} minValue
139      * The minimum allowed value (defaults to Number.NEGATIVE_INFINITY). Will be used by the field's validation logic,
140      * and for {@link Ext.form.field.Spinner#setSpinUpEnabled enabling/disabling the down spinner button}.
141      */
142     minValue: Number.NEGATIVE_INFINITY,
143
144 <span id='Ext-form-field-Number-cfg-maxValue'>    /**
145 </span>     * @cfg {Number} maxValue
146      * The maximum allowed value (defaults to Number.MAX_VALUE). Will be used by the field's validation logic, and for
147      * {@link Ext.form.field.Spinner#setSpinUpEnabled enabling/disabling the up spinner button}.
148      */
149     maxValue: Number.MAX_VALUE,
150
151 <span id='Ext-form-field-Number-cfg-step'>    /**
152 </span>     * @cfg {Number} step
153      * Specifies a numeric interval by which the field's value will be incremented or decremented when the user invokes
154      * the spinner.
155      */
156     step: 1,
157
158 <span id='Ext-form-field-Number-cfg-minText'>    /**
159 </span>     * @cfg {String} minText
160      * Error text to display if the minimum value validation fails.
161      */
162     minText : 'The minimum value for this field is {0}',
163
164 <span id='Ext-form-field-Number-cfg-maxText'>    /**
165 </span>     * @cfg {String} maxText
166      * Error text to display if the maximum value validation fails.
167      */
168     maxText : 'The maximum value for this field is {0}',
169
170 <span id='Ext-form-field-Number-cfg-nanText'>    /**
171 </span>     * @cfg {String} nanText
172      * Error text to display if the value is not a valid number. For example, this can happen if a valid character like
173      * '.' or '-' is left in the field with no number.
174      */
175     nanText : '{0} is not a valid number',
176
177 <span id='Ext-form-field-Number-cfg-negativeText'>    /**
178 </span>     * @cfg {String} negativeText
179      * Error text to display if the value is negative and {@link #minValue} is set to 0. This is used instead of the
180      * {@link #minText} in that circumstance only.
181      */
182     negativeText : 'The value cannot be negative',
183
184 <span id='Ext-form-field-Number-cfg-baseChars'>    /**
185 </span>     * @cfg {String} baseChars
186      * The base set of characters to evaluate as valid numbers.
187      */
188     baseChars : '0123456789',
189
190 <span id='Ext-form-field-Number-cfg-autoStripChars'>    /**
191 </span>     * @cfg {Boolean} autoStripChars
192      * True to automatically strip not allowed characters from the field.
193      */
194     autoStripChars: false,
195
196     initComponent: function() {
197         var me = this,
198             allowed;
199
200         me.callParent();
201
202         me.setMinValue(me.minValue);
203         me.setMaxValue(me.maxValue);
204
205         // Build regexes for masking and stripping based on the configured options
206         if (me.disableKeyFilter !== true) {
207             allowed = me.baseChars + '';
208             if (me.allowDecimals) {
209                 allowed += me.decimalSeparator;
210             }
211             if (me.minValue &lt; 0) {
212                 allowed += '-';
213             }
214             allowed = Ext.String.escapeRegex(allowed);
215             me.maskRe = new RegExp('[' + allowed + ']');
216             if (me.autoStripChars) {
217                 me.stripCharsRe = new RegExp('[^' + allowed + ']', 'gi');
218             }
219         }
220     },
221
222 <span id='Ext-form-field-Number-method-getErrors'>    /**
223 </span>     * Runs all of Number's validations and returns an array of any errors. Note that this first runs Text's
224      * validations, so the returned array is an amalgamation of all field errors. The additional validations run test
225      * that the value is a number, and that it is within the configured min and max values.
226      * @param {Object} [value] The value to get errors for (defaults to the current field value)
227      * @return {String[]} All validation errors for this field
228      */
229     getErrors: function(value) {
230         var me = this,
231             errors = me.callParent(arguments),
232             format = Ext.String.format,
233             num;
234
235         value = Ext.isDefined(value) ? value : this.processRawValue(this.getRawValue());
236
237         if (value.length &lt; 1) { // if it's blank and textfield didn't flag it then it's valid
238              return errors;
239         }
240
241         value = String(value).replace(me.decimalSeparator, '.');
242
243         if(isNaN(value)){
244             errors.push(format(me.nanText, value));
245         }
246
247         num = me.parseValue(value);
248
249         if (me.minValue === 0 &amp;&amp; num &lt; 0) {
250             errors.push(this.negativeText);
251         }
252         else if (num &lt; me.minValue) {
253             errors.push(format(me.minText, me.minValue));
254         }
255
256         if (num &gt; me.maxValue) {
257             errors.push(format(me.maxText, me.maxValue));
258         }
259
260
261         return errors;
262     },
263
264     rawToValue: function(rawValue) {
265         var value = this.fixPrecision(this.parseValue(rawValue));
266         if (value === null) {
267             value = rawValue || null;
268         }
269         return  value;
270     },
271
272     valueToRaw: function(value) {
273         var me = this,
274             decimalSeparator = me.decimalSeparator;
275         value = me.parseValue(value);
276         value = me.fixPrecision(value);
277         value = Ext.isNumber(value) ? value : parseFloat(String(value).replace(decimalSeparator, '.'));
278         value = isNaN(value) ? '' : String(value).replace('.', decimalSeparator);
279         return value;
280     },
281
282     onChange: function() {
283         var me = this,
284             value = me.getValue(),
285             valueIsNull = value === null;
286
287         me.callParent(arguments);
288
289         // Update the spinner buttons
290         me.setSpinUpEnabled(valueIsNull || value &lt; me.maxValue);
291         me.setSpinDownEnabled(valueIsNull || value &gt; me.minValue);
292     },
293
294 <span id='Ext-form-field-Number-method-setMinValue'>    /**
295 </span>     * Replaces any existing {@link #minValue} with the new value.
296      * @param {Number} value The minimum value
297      */
298     setMinValue : function(value) {
299         this.minValue = Ext.Number.from(value, Number.NEGATIVE_INFINITY);
300     },
301
302 <span id='Ext-form-field-Number-method-setMaxValue'>    /**
303 </span>     * Replaces any existing {@link #maxValue} with the new value.
304      * @param {Number} value The maximum value
305      */
306     setMaxValue: function(value) {
307         this.maxValue = Ext.Number.from(value, Number.MAX_VALUE);
308     },
309
310     // private
311     parseValue : function(value) {
312         value = parseFloat(String(value).replace(this.decimalSeparator, '.'));
313         return isNaN(value) ? null : value;
314     },
315
316 <span id='Ext-form-field-Number-method-fixPrecision'>    /**
317 </span>     * @private
318      */
319     fixPrecision : function(value) {
320         var me = this,
321             nan = isNaN(value),
322             precision = me.decimalPrecision;
323
324         if (nan || !value) {
325             return nan ? '' : value;
326         } else if (!me.allowDecimals || precision &lt;= 0) {
327             precision = 0;
328         }
329
330         return parseFloat(Ext.Number.toFixed(parseFloat(value), precision));
331     },
332
333     beforeBlur : function() {
334         var me = this,
335             v = me.parseValue(me.getRawValue());
336
337         if (!Ext.isEmpty(v)) {
338             me.setValue(v);
339         }
340     },
341
342     onSpinUp: function() {
343         var me = this;
344         if (!me.readOnly) {
345             me.setValue(Ext.Number.constrain(me.getValue() + me.step, me.minValue, me.maxValue));
346         }
347     },
348
349     onSpinDown: function() {
350         var me = this;
351         if (!me.readOnly) {
352             me.setValue(Ext.Number.constrain(me.getValue() - me.step, me.minValue, me.maxValue));
353         }
354     }
355 });
356 </pre>
357 </body>
358 </html>