Mask Type: Numeric

• Aug 28, 2020
• 5 minutes to read

Overview

The Numeric mask type allows users to enter numeric values (integer, float values, currencies, percentages, etc.). The numeric mask type supports the standard numeric .Net format.

Note

Run the XtraEditors demo to try out input masks.

Mask Type and Mask Expression

The TextEdit.Properties.Mask property provides access to a MaskProperties class instance that specifies an input mask. Set the MaskProperties.MaskType property to Numeric to enable the numeric mask type. Use the MaskProperties.EditMask property to specify the mask expression.

Note

If an editor’s value is an integer number, users are not allowed to enter the number’s fraction part, even if the mask displays it.

Standard Masks

A standard numeric mask consists of a mask and 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 specifies different patterns in the USA and France (the currency symbol, the thousand separator, the precision, etc.). The CultureInfo.NumberFormat property specifies a culture’s numeric format. Users can change the regional format in the Windows Settings panel.

Specifier	Description	Remarks	Example (English (USA) culture)
C or c	Currency.	Users cannot edit the currency symbol. 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.CurrencyDecimalDigits property.	Mask: c Value: 1024.5 Mask: c0 Value: 20010
D or d	Integer decimal number.	If the editor’s value is a non-integer number, the mask discards the fraction part. The precision specifies the number of digits. If no precision is specified, the default is the minimum value required to represent the integer without leading zeros.	Mask: d Value: 1501
F or f G or g	Non-integer decimal 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.	Mask: f Value: 1024.5
N or n	Integer or non-integer decimal number.	The mask displays group (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.	Mask: n Value: 1024.5
P	Percentage.	Displays the value as it is. The masks matches the pattern specified by the culture’s CultureInfo.NumberFormat.PercentNegativePattern and CultureInfo.NumberFormat.PercentPositivePattern properties. 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.	Mask: P Value: 25
p	Percentage.	Multiplies the value by 100. The masks matches the pattern specified by the culture’s CultureInfo.NumberFormat.PercentNegativePattern and CultureInfo.NumberFormat.PercentPositivePattern properties. 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.	Mask = p Value = 0.25

Custom Masks

Use the following placeholders and special characters to build custom numeric masks.

Placeholder	Name	Description
#	Digit.	Users can enter a decimal digit (0-9) at this position. If the user does not enter a digit, the editor does not fill this position with zero. Note that if the mask is “#” and the value is “0”, the editor displays an empty string.
0	Digit with default zero.	Users can enter a decimal digit (0-9) at this position. If the user does not enter a digit, the editor fills this position with zero.
.	Decimal point.	Specifies the decimal separator’s location. The culture’s CultureInfo.NumberFormat.NumberDecimalSeparator property specifies the actual decimal separator.
,	Group (thousand) separators.	Enables group (thousand) separators. The culture’s CultureInfo.NumberFormat.NumberGroupSizes property specifies the number of digits in each group. The NumberGroupSeparator property specifies the group separator character. If the mask contains the currency symbol ($), the CurrencyGroupSizes and CurrencyGroupSeparator properties are used. If the mask contains a percent symbol (%), the PercentGroupSizes and PercentGroupSeparator properties are used.
%	Percentage character.	Multiplies the value by 100. The culture’s CultureInfo.NumberFormat.PercentSymbol property specifies the percent symbol.
%%	Percentage character.	Displays the value as it is. The culture’s CultureInfo.NumberFormat.PercentSymbol property specifies the percent symbol.
\	Escape character.	Precede a placeholder or special character with a backslash to display the character in the edit box.
;	Mask separator.	Separates masks for positive and negative values. The left-hand expression specifies the mask for positive values; right-hand - for negative values. If the right-hand expression is omitted, the editor does not allow users to enter negative values.
$	Currency character.	The culture’s CultureInfo.NumberFormat.PerceCurrencySymbolntSymbol property specifies the currency symbol.
	Any other characters.	Any other characters are displayed in the edit box literally.

Examples

Example 1

#,##0.00 - a real number that has from 1 to 4 digits in the integer part and 2 digits in the fractional part. The integer part is divided into groups by three.

• Value: 3080.6

  

• Value: -3080.6

  

Example 2

#,##0.00;<<#,##0.00>> - a mask that encloses negative values with double angle brackets.

• Value: -3080.6

  

End-User Capabilities

• The Minus sign 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 part.