Mask Type: Numeric

  • 9 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

C or c

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")
$323.0 ("C1")
$323 ("C0")

D or d

Whole numbers. The fraction part is automatically discarded. The precision specifies the total number of digits.

-005 ("d3")
02 ("d2")
1234 ("d" or "d4")

F or f
G or g

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")
1024.500 ("f3")

N or n

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")
1,024.500 ("n3")

P

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.

The mask matches the pattern specified by the culture's CultureInfo.NumberFormat.PercentNegativePattern and CultureInfo.NumberFormat.PercentPositivePattern properties.

25.00% ("P" or "P2", editor value is "25")
25% ("P0", editor value is "25")

p

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.

The mask matches the pattern specified by the culture's CultureInfo.NumberFormat.PercentNegativePattern and CultureInfo.NumberFormat.PercentPositivePattern properties.

2500.00% ("P" or "P2", editor value is "25")
2500% ("P0", 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)
1 ("###", editor value is 1)
123 ("###", editor value is 123)

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)
1 ("##0", editor value is 1)
123 ("##0", editor value is 123)

.

Decimal point. The character used as a decimal point separator is specified by the CultureInfo.NumberFormat.NumberDecimalSeparator property.

.9 ("#.#", editor value is 0.9)
0.9 ("0.#", editor value is 0.9)
0.900 ("0.000", editor value is 0.91)
123.0 ("##0.0", editor value is 123)

,

Group (thousand) separator.

The character used as a group separator is specified by the NumberGroupSeparator property, and the number of digits in each group - by the CultureInfo.NumberFormat.NumberGroupSizes property.

If the mask contains the currency symbol ($), the CurrencyGroupSeparator and CurrencyGroupSizes properties are used instead.

If the mask contains a percent symbol (%), the PercentGroupSizes and PercentGroupSeparator properties are used instead.

-3080.60 ("#,##0.00", editor value is -3080.6)
10,000 ("##,###", editor value is 10000)
100 ("##,###", editor value is 100)

%

Percentage. Multiples 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)
0.31% ("#0.00%%", editor value is 0.3124)

\

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 optional DateTime settings.

Advanced Numeric 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.

Value after delete

If the "Value after delete" property is "Null", the editor sets its value to "null" immediately after the last digit is removed.

Value after delete 2

Note that if the editor mask has only hash metacharacters (for instance, "####"), it 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 completely clear the editor and set its EditValue to "null".

Value after delete 3

//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; }

"Hide decimal separator for whole numbers"

If an editor accepts real numbers, enable this setting to hide the decimal separator when a user enter 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.

hide decimal separator

If a user enters "250.00", the editor shows "$250.00" when focused, regardless of this setting.

hide decimal separator when the editor is focused

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).

Hide insignificant zeros is true or not set

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 value that matches its underlying data.

Hide insignificant zeros is false

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".

significant zero step 1

The user presses the left arrow key five times, until the caret is positioned after "1".

significant zero step 2

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.

significant zero step 3

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.

significant zero step 4

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.

significant zero step 5 true or significant zero step 5 false

//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.
See Also