Mask Type: Numeric

• Mar 03, 2023
• 9 minutes to read

This document describes the Numeric mask type, which is specifically designed for entering numeric values (integer, float values, currencies, percentages, etc.) and for controlling how they are subsequently displayed. Numeric masks are dependent upon the current culture (regional) settings.

For information on other available masked modes, see the Mask Types document.

Numeric Mask Mode

To enable the Numeric mask type, set the editor’s TextEdit.MaskType (or the TextEditSettings.MaskType for the in-place editors) property to MaskType.Numeric. The mask itself should be specified using the TextEdit.Mask (or TextEditSettings.Mask) property.

You can use either predefined or custom masks. These masks are similar to display formats that are described in the Numeric Format Strings document in MSDN, and so the editor’s edit mask and display format may match. Set the TextEdit.MaskUseAsDisplayFormat (TextEditSettings.MaskUseAsDisplayFormat for in-place editors) to format editor values using mask when the editor is not in edit mode.

Most of the masks listed below are affected by the current culture. For instance, the culture defines the currency symbol, the symbol to use as a thousand separator, the default number of digits to the right of the decimal point, etc. All these settings are provided by the NumberFormat property of the current culture. To customize these settings, use the Regional Options dialog in the control panel.

Note

If an editor’s edit value is of an integer type, the editor only accepts integer values. An end user cannot enter a fractional part of a number, even if it is allowed by the editor’s mask.

Masks used to enter values with decimal part make editor to display a decimal separator. Set the attached NumericMaskOptions.AlwaysShowDecimalSeparator property to false to hide a decimal separator when the decimal part is zero:

XAML

<dxe:TextEdit dxe:NumericMaskOptions.AlwaysShowDecimalSeparator="False" Mask="##.##" MaskType="Numeric" .../>

Predefined Masks

Predefined masks allow end-users to edit numeric values of common numeric types. A standard mask represents a string of the Axx form where A is a single alphabetical character (mask specifier), and xx is an optional integer called the precision specifier. The available mask specifiers are listed in the following table. The precision specifier ranges from 0 to 99 and controls the number of significant digits or zeroes to the right of the decimal point.

Specifier	Name	Description	Samples Culture: English (USA)
C or c	Currency	The mask for entering a currency amount. The edit mask contains a value part that can be edited by an end-user, and a currency symbol that cannot be edited. The mask’s format is determined by the current culture. Various settings that affect how numeric values are represented by the current culture are provided by the NumberFormat property of the current culture. The precision specifier indicates the desired number of decimal places. If the precision specifier is omitted, the default currency precision declared in the NumberFormat object is used.	(EditMask = “c”; EditValue = 1024.5) (EditMask = “c0”; EditValue = 20010)
D or d	Decimal	The mask for entering integer values of a fixed and flexible length. The precision specifier indicates the maximum number of digits that can be entered. If the precision specifier is equal to 0 or omitted, the length of the input string is not limited. If the editor’s value is real, the fractional part of the value is discarded during editing.	(EditMask = “d”; EditValue = 1501)
F or f G or g	Fixed-point	The mask for entering real numbers with a fixed-length fractional part. The precision specifier indicates the desired number of decimal places. If the precision specifier is omitted, the default numeric precision declared in the NumberFormat object is used.	(EditMask = “f”; EditValue = 1024.5)
N or n	Number	The mask for entering the integers of real values. Thousand separators are inserted between each group of three digits to the left of the decimal point. The precision specifier indicates the desired number of decimal places. If the precision specifier is omitted, the default numeric precision declared in the NumberFormat is used.	(EditMask = “n”; EditValue = 1024.5)
P	Percent (mode 1)	The mask for entering percentages. The entered string is converted into a number “as is” (compare with the p mask). For example, if the “15 %” string is entered, the editor’s value is 15. The mask’s format is determined by the PercentNegativePattern and PercentPositivePattern properties, depending upon the sign of the entered number. The precision specifier indicates the desired number of decimal places. If the precision specifier is omitted, the default numeric precision declared in the NumberFormat object is used. If you display an editor value as a percent, the p and P format specifiers are similar.	(EditMask = “P”; EditValue = 25)
p	Percent (mode 2)	The mask for entering percentages. The entered string is converted to a number and then divided by 100. The result is used as the editor’s value (compare with the P mask). For example, if the “15 %” string is entered, the editor’s value is 0.15. The mask’s format is determined by the PercentNegativePattern and PercentPositivePattern properties, depending upon the sign of the entered number. The precision specifier indicates the desired number of decimal places. If the precision specifier is omitted, the default numeric precision declared in the NumberFormat object is used.	(EditMask = “p”; EditValue = 0.25)

Custom Masks

If the predefined masks do not suit your particular needs, custom masks can be used. You can use the following characters to create custom masks for editing numeric values.

Character	Name	Description
0	Zero placeholder	A decimal digit (0-9) can be entered in the corresponding position. Empty placeholders are represented by 0 characters. When the input string is converted to the editor’s value, digits left empty are interpreted as zeros.
#	Digit placeholder	A decimal digit (0-9) can be entered in the corresponding position or left empty. The empty placeholders are not displayed. When the input string is converted to the editor’s value, digits left empty are not stored in the result. Example: If a mask is #, the edit value of 0 is formatted as an empty string.
.	Decimal point	The first . character in the format string determines the location of the decimal separator in the formatted value. The actual character used as the decimal separator is determined by the System.Globalization.NumberFormatInfo.NumberDecimalSeparator property.
,	Thousand separator	If the , character appears in the mask, thousand separators are inserted between each group of digits to the left of the decimal point as defined by the NumberFormat object. If the mask contains the currency symbol ($), the number of digits in each group is determined by the CurrencyGroupSizes property. The character representing the group separator is determined by the CurrencyGroupSeparator property. If the mask contains a percent symbol (%), the number of digits in each group is determined by the PercentGroupSizes property. The character representing the group separator is determined by the PercentGroupSeparator property. If the mask doesn’t contain currency or percent symbols, the number of digits in each group is determined by the NumberGroupSizes property. The character representing the group separator is determined by the NumberGroupSeparator property.
%	Percentage placeholder	If the % character appears in the mask, the value entered is divided by 100 when converted into the editor’s value. For example, if the ‘15 %’ string is entered, the edit value is ‘0.15’. The percent character used is dependent upon the current culture. An appropriate symbol is inserted in the edit box at the location where the % symbol appears in the mask.
%%	Percentage placeholder	If the %% string appears in the mask, the entered value is not divided by 100 when it is converted into the editor’s value. For example, if the ‘15 %’ string is entered, the edit value is ‘15’. The percent character used is dependent upon the current culture. An corresponding symbol is inserted in the edit box at the location where the ‘%’ symbol appears in the mask.
\	Escape character	The character following the escape character is inserted into the edit box literally. To display a backslash in the edit box, the mask should contain the \\ string.
;	Section separator	The ; character is used to separate the masks for positive and negative values. The mask can contain two parts delimited by the ; character. The first part defines the mask for entering positive values, the second part specifies a mask for entering negative values. An end user can toggle the value’s sign by pressing the - key. In this case, depending upon the value’s sign, the entered value is reformatted using the corresponding mask. If the ; character and mask for negative values are omitted, the editor uses the default pattern for negative values determined by the NumberFormat object. If the ; character is followed by an empty string, the editor prevents end users from entering negative values. Numeric masks allow you to specify only two parts (standard masks include the third part for zero values). Refer to the following help topic for information on how to format zero values: BaseEdit.NullValue.
$	Currency character	Defines the position of the currency symbol determined by the current culture. This symbol can be accessed via the CurrencySymbol property.
Any other character	Literal character	All other characters that appear in the mask are inserted into the edit box literally. To display special characters in the edit box literally, they should be preceded with the escape character (\).

End-User Capabilities

Numeric masks allow end-users to enter numeric values only. Text cannot be edited in this mask mode.

• Pressing the ‘-‘ key changes the sign of the value being edited. The caret can be placed at any position within the edit box.
• Pressing the Up-Arrow and Down-Arrow keys increments or decrements the digit to the left of the caret’s position. If the entire text is selected, pressing these keys increments or decrements the digit to the left of the decimal point.
• Scrolling the mouse wheel increments or decrements the digit to the left of the caret’s position. If the entire text is selected, scrolling the mouse wheel increments or decrements the digit to the left of the decimal point.

Numeric Mask Options

The NumericMaskOptions class provides a set of attached properties useful to customize the input of numeric values.

Examples

The following are examples of custom numeric masks. See the table in the Predefined Masks sub-section for examples of predefined masks.

1. A mask for entering a real number that has a maximum of 4 digits to the left of the decimal point: #,##0.00

   Groups of three digits is separated with thousand separators. The fractional part of the value always contains two digits.

   (EditValue = 3080.6);

   (EditValue = -3080.6).

2. The same mask for positive values. Negative values are enclosed with double angle brackets: #,##0.00;<<#,##0.00>>

   (EditValue = -3080.6).