[Expand]General Information
[Expand]WinForms Controls
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Collapse]WPF Controls
  Prerequisites
 [Expand]What's Installed
 [Expand].NET Core 3 Support
 [Expand]Common Concepts
 [Expand]MVVM Framework
 [Collapse]Controls and Libraries
   Reporting
  [Expand]Data Grid
  [Expand]Ribbon, Bars and Menu
  [Expand]Charts Suite
  [Expand]Pivot Grid
  [Expand]Scheduler
  [Expand]Spreadsheet
  [Expand]Rich Text Editor
  [Expand]Tree List
  [Expand]Gauge Controls
  [Expand]Map Control
  [Expand]Layout Management
  [Expand]Windows Modern UI
  [Expand]Printing-Exporting
  [Collapse]Data Editors
    Included Components
   [Expand]Implementation Details
   [Expand]Getting Started
   [Expand]Editor Types
   [Collapse]Common Features
    [Expand]Obtaining Editor Values
    [Expand]Binding to Data
     In-Place Mode
    [Expand]Editor Operation Modes
    [Collapse]Masked Input
      Mask Type: Date-Time
      Mask Type: TimeSpan
      Mask Type: Extended Regular Expressions
      Mask Type: Numeric
      Mask Type: Simple
      Mask Type: Simplified Regular Expressions
    [Expand]Input Validation
     Incremental Search
     Filtering
   [Expand]Range Control
   [Expand]Visual Elements
   [Expand]End-User Capabilities
   [Expand]Examples
  [Expand]Navigation Controls
  [Expand]Spell Checker
  [Expand]Property Grid
  [Expand]PDF Viewer
  [Expand]TreeMap Control
  [Expand]Gantt Control
  [Expand]Diagram Control
  [Expand]Windows and Utility Controls
   Dialogs, Notifications and Panels
  [Expand]Scheduler (legacy)
 [Expand]Scaffolding Wizard
 [Expand]Localization
  Redistribution and Deployment
  Get More Help
 [Expand]API Reference
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Office File API
[Expand]Reporting
[Expand]Report and Dashboard Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]eXpress Persistent Objects
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation
View this topic on docs.devexpress.com (Learn more)

Mask Type: Numeric

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.

In this topic:

Expanded 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 System.Globalization.CultureInfo.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:

Expanded 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 alphabetic 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 System.Globalization.CultureInfo.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 will be 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). So, if the "15 %" string is entered, the editor's value will be 15.

The mask's format is determined by the System.Globalization.NumberFormatInfo.PercentNegativePattern and System.Globalization.NumberFormatInfo.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 = 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). So, if the "15 %" string is entered, the editor's value will be 0.15.

The mask's format is determined by the System.Globalization.NumberFormatInfo.PercentNegativePattern and System.Globalization.NumberFormatInfo.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)

Expanded 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. 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 set to "#", the edit value of 0 will be 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 will be 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 System.Globalization.NumberFormatInfo.CurrencyGroupSizes property. The character representing the group separator is determined by the System.Globalization.NumberFormatInfo.CurrencyGroupSeparator property.

If the mask contains a percent symbol (%), the number of digits in each group is determined by the System.Globalization.NumberFormatInfo.PercentGroupSizes property. The character representing the group separator is determined by the System.Globalization.NumberFormatInfo.PercentGroupSeparator property.

If the mask doesn't contain currency or percent symbols, the number of digits in each group is determined by the System.Globalization.NumberFormatInfo.NumberGroupSizes property. The character representing the group separator is determined by the System.Globalization.NumberFormatInfo.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. So, if the '15 %' string is entered, the edit value will be '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. So, if the '15 %' string is entered, the edit value will be '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 value entered is automatically reformatted using the corresponding mask.

If the ";" character and mask for negative values are omitted, the editor will use the default pattern for negative values determined by the NumberFormat object.

If the ";" character is followed by an empty string, the editor will not allow end-users to enter negative values.

$

Currency character

Defines the position of the currency symbol determined by the current culture. This symbol can be accessed via the System.Globalization.NumberFormatInfo.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 ('').

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

Expanded 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 will be separated using thousand separators. The fractional part of the value will always contain two digits.

(EditValue = 3080.6);

(EditValue = -3080.6).

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

(EditValue = -3080.6).

Is this topic helpful?​​​​​​​