Mask Type: Numeric
- 10 minutes to read
The Numeric mask type allows users to enter numeric values (integer, float, currency, percentage, etc.). This mask type supports the standard numeric .NET format.
Run this Demo Center module to test various input masks: Mask Box.
Standard Masks
A standard numeric mask consists of a mask and a precision specifier. The precision specifier ranges from 0 to 99 and sets the number of digits to the left or the right of a decimal point (depending on the mask specifier).
The table below contains input masks that correspond to the standard patterns. Note that patterns depend on the current culture. For example, the same input mask may specify different patterns in the U.S. and France (the currency symbol, the thousand separator, the precision, etc.). The CultureInfo.NumberFormat property specifies the culture’s numeric format. Users can change the regional format in the Windows Settings panel.
Specifier | Description | Sample |
|---|---|---|
| Currency. Users cannot edit the currency symbol. Precision specifies the number of digits after the decimal point. If the precision is not set, the editor uses the number stored in the CultureInfo.NumberFormat.CurrencyDecimalDigits property. | $323.00 (“C”) |
| Whole numbers. The fraction part is automatically discarded. The precision specifies the total number of digits. | -005 (“d3”) |
| Real number. The precision specifies the number of digits to the right of a decimal point. If the precision specifier is omitted, the mask uses the culture’s CultureInfo.NumberFormat.NumberDecimalDigits property. | 1024.5 (“f”) |
| Real number with thousand separators. The precision specifies the number of digits to the right of a decimal point. If the precision specifier is omitted, the mask uses the culture’s CultureInfo.NumberFormat.NumberDecimalDigits property. | 1,024.5 (“n”) |
| Percentage. Displays the value as is. The precision specifies the number of digits to the right of a decimal point. If the precision specifier is omitted, the mask uses the culture’s CultureInfo.NumberFormat.PercentDecimalDigits property. | 25.00% (“P” or “P2”, editor value is “25”) |
| Percentage. Multiplies the value by 100. The precision specifies the number of digits to the right of a decimal point. If the precision specifier is omitted, the mask uses the culture’s CultureInfo.NumberFormat.PercentDecimalDigits property. | 2500.00% (“P” or “P2”, editor value is “25”) |
Custom Masks
Use the following placeholders and special characters to build custom numeric masks.
Placeholder | Description | Example |
|---|---|---|
| Any digit (0-9). The editor shows nothing for “#” placeholders that have no value. | <empty> (“###”, editor value is 0) |
| Any digit (0-9). The default value is zero. The editor shows zeros for “0” placeholders that have no value. | 0 (“##0”, editor has no value) |
| Decimal point. The character used as a decimal point separator is specified by the CultureInfo.NumberFormat.NumberDecimalSeparator property. | .9 (“#.#”, editor value is 0.9) |
| Group (thousand) separator. | -3080.60 (“#,##0.00”, editor value is -3080.6) |
| Percentage. Multiplies the editor value by 100. The percent symbol is specified by the CultureInfo.NumberFormat.PercentSymbol property. | -31.24% (“#0.00%”, editor value is -0.3124) |
| Percentage character. Displays the editor value as is. The percent symbol is specified by the CultureInfo.NumberFormat.PercentSymbol property. | -31.24% (“#0.00%%”, editor value is -31.24) |
| Escape character. Any character that follows the escape character is inserted into the edit box literally. To display a backslash in the edit box, type the “\\” string. | % complete: 10.25 (“\% complete: #0.00”, editor value is 10.25) |
| Allows you to set up different mask expressions for positive (left-hand expression) and negative (right-hand expression) values. If there is no expression after this placeholder, the editor does not allow users to enter negative values. | The “#,##0.00;<<#,##0.00>>” mask displays positive values as is, and encloses negative values in double angled brackets (“3080.6” or “<<-3,080.6>>)” |
| Currency character. The currency symbol is specified by the CultureInfo.NumberFormat.PerceCurrencySymbolntSymbol property. | 30 $ (“###0 $”) |
Any other characters. | Any other characters are displayed in the edit box as is. |
Numeric Mask Options
When you click the ellipsis button next to the MaskSettings property, the Mask Settings dialog appears. Click “Show Advanced Options” in the bottom left corner to view additional settings.
To apply these settings in code, call the MaskSettings.Configure<MaskSettings.Numeric> method and set up the required options for the method return parameter.
“Value after delete”
This property is in effect only when the editor can accept “null” as its EditValue (see the AllowNullInput property).
When a user presses Backspace or Delete, the “Value after delete” property specifies the value this editor receives after the last digit is removed. If this property is “ZeroThenNull”, the editor value becomes “0”. A user can press Backspace/Delete once more to remove this zero, and the editor value becomes “null”. Note that if a user has cleared an entire editor (the user pressed the Ctrl+Del hotkey combination or selected the entire text and removed it), EditValue becomes “null” immediately.
If the “Value after delete” property is “Null”, the editor sets its value to “null” immediately after the last digit is removed.
Note that if the editor mask has only hash metacharacters (for instance, “####”), the editor appears empty as soon as a user removes the last digit. However, if the “Value after delete” is “ZeroThenNull”, the underlying editor’s EditValue is still 0. A user must press Ctrl+Del to clear the editor completely and set its EditValue to “null”.
// Fluent API
using DevExpress.XtraEditors.Mask;
textEdit5.Properties.MaskSettings.Configure<MaskSettings.Numeric>(settings => {
settings.MaskExpression = "##0";
settings.ValueAfterDelete = NumericMaskManager.ValueAfterDelete.ZeroThenNull;
});
// Regular API
using DevExpress.XtraEditors.Mask;
var settings = textEdit5.Properties.MaskSettings.Configure<MaskSettings.Numeric>();
settings.MaskExpression = "##0";
settings.ValueAfterDelete = NumericMaskManager.ValueAfterDelete.ZeroThenNull;
// Data source level (for code-first sources)
using System.ComponentModel.DataAnnotations;
[NumericEditMask("##0", ValueAfterDelete = NumericMaskManager.ValueAfterDelete.ZeroThenNull)]
public int Quantity { get; set; }
Value Type
The Value Type setting allows you to specify the output data type for an editor with a numeric mask. When a user enters values within the edit box, the data editor converts the input string to the specified output data type and assigns the result to the editor’s value.
If you do not specify the Value Type setting, the editor determines the output data type as follows:
- From the bound field’s type (in bound mode)
- From the type of the editor’s initial value (in unbound mode)
// Fluent API
using DevExpress.XtraEditors.Mask;
textEdit1.Properties.MaskSettings.Configure<MaskSettings.Numeric>(settings => {
settings.MaskExpression = "N";
settings.ValueType = typeof(double);
});
// Regular API
using DevExpress.XtraEditors.Mask;
var settings = textEdit1.Properties.MaskSettings.Configure<MaskSettings.Numeric>();
settings.MaskExpression = "N";
settings.ValueType = typeof(double);
// Data source level (for code-first sources)
using System.ComponentModel.DataAnnotations;
[NumericEditMask("N", ValueType = typeof(double))]
public decimal Price { get; set; }
“Hide decimal separator for whole numbers”
If an editor accepts real numbers, enable this setting to hide the decimal separator when a user enters a whole number (a number with no fractional part). For example, if the editor mask is “$##0.##” and a user enters “250”, the editor displays “250.” when this setting is disabled, and “250” when enabled.
If a user enters “250.00”, the editor shows “$250.00” when focused, regardless of this setting.
This setting does not hide the fractional part if it contains “0” placeholders instead of “#” (for example, “$##0.00”). In this instance, even when a user enters “250” and the “Hide decimal separator” setting is enabled, the editor shows “$250.00”.
// Fluent API
using DevExpress.XtraEditors.Mask;
textEdit5.Properties.MaskSettings.Configure<MaskSettings.Numeric>(settings => {
settings.MaskExpression = "$##0.##";
settings.AutoHideDecimalSeparator = true;
});
// Regular API
using DevExpress.XtraEditors.Mask;
var settings = textEdit5.Properties.MaskSettings.Configure<MaskSettings.Numeric>();
settings.MaskExpression = "$##0.##";
settings.AutoHideDecimalSeparator = true;
// Data source level (for code-first sources)
using System.ComponentModel.DataAnnotations;
[NumericEditMask("$##0.##", AutoHideDecimalSeparator = true)]
public decimal Price { get; set; }
“Hide insignificant zeros”
This property has effect only for masks (mask segments) that consist solely of the “#” metacharacter. When all digits in an editor with this mask type are removed, the editor shows nothing. Its EditValue, however, is “0” (not null or String.Empty).
To eliminate this confusion, disable the “Hide insignificant zeros” property. When a user removes the last editor digit, the editor shows “0” and the EditValue is 0. Or, if the “Value after delete” property is “Null”, the editor shows nothing and its EditValue is null. In either case, the editor shows a value that matches its underlying data.
Note that “significant” zeros remain visible regardless of this property. A zero is considered significant if both of the following criteria are met:
- It is located in the currently edited portion of a number.
- It is located between the current caret position and the decimal point.
For example, the editor has the “###.##” mask and a user enters “100.20”.
The user presses the left arrow key five times, until the caret is positioned after “1”.
The user then presses “Backspace” and removes “1”. In the whole number portion, both zeros are located between the caret and the decimal point. These zeros are significant and remain visible. The fractional part (after the decimal point) is not currently being edited, so its zero is hidden.
The user moves the caret to the end of the fractional part and enters “0”. The whole number part is no longer being edited, so its zeros disappear.
The user presses the “Backspace” key twice. The editor now shows “.” if the “Hide insignificant zeros” property is set to true or default. Otherwise, the previously empty whole number portion shows “0” to match the EditValue property value.
or 
// Fluent API
using DevExpress.XtraEditors.Mask;
textEdit5.Properties.MaskSettings.Configure<MaskSettings.Numeric>(settings => {
settings.MaskExpression = "###.##";
settings.HideInsignificantZeros = true;
});
// Regular API
using DevExpress.XtraEditors.Mask;
var settings = textEdit5.Properties.MaskSettings.Configure<MaskSettings.Numeric>();
settings.MaskExpression = "###.##";
settings.HideInsignificantZeros = true;
// Data source level (for code-first sources)
using System.ComponentModel.DataAnnotations;
[NumericEditMask("###.##", HideInsignificantZeros = true)]
public decimal Weight { get; set; }
End-User Capabilities
- The Minus key on the numeric keypad changes the number’s sign. The caret can be placed at any position in the edit box.
- The Up/Down Arrow keys and the mouse wheel increment and decrement the digit to the left of the caret. If the entire number is selected, these keys increment and decrement the number’s integer portion.