Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Collapse]WinForms Controls
  Prerequisites
 [Expand]What's Installed
 [Expand]Build an Application
 [Collapse]Controls and Libraries
  [Expand]Forms and User Controls
  [Expand]Messages, Notifications and Dialogs
  [Collapse]Editors and Simple Controls
   [Collapse]Simple Editors
    [Expand]Included Components
    [Expand]Editors Structure
    [Collapse]Editors Features
      Text Editing Overview
     [Collapse]Mask Editors Overview
       Mask Type: Numeric
       Mask Type: Date-time
       Mask Type: Extended Regular Expressions
       Mask Type: Simple
       Mask Type: Simplified Regular Expressions
     [Expand]Formatting and Parsing Values
     [Expand]Editor Buttons Overview
     [Expand]Dropdown Editors Overview
      Image Editing Menu
     [Expand]Data Binding Overview
     [Expand]Appearance Customization
     [Expand]Miscellaneous Features
    [Expand]Member Tables
    [Expand]Examples
   [Expand]Lookup Editors
   [Expand]Token Edit Control
   [Expand]Breadcrumb Edit Control
   [Expand]Range Control
   [Expand]Image Slider
    Camera Control
  [Expand]Ribbon, Bars and Menu
  [Expand]Application UI Manager
  [Expand]Docking Library
  [Expand]Data Grid
  [Expand]Vertical Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Chart Control
  [Expand]Diagrams
  [Expand]Gauges
  [Expand]Map Control
  [Expand]Scheduler
  [Expand]Spreadsheet
  [Expand]Rich Text Editor
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]Printing-Exporting
  [Expand]PDF Viewer
   Reporting
  [Expand]Snap
  [Expand]TreeMap Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

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 Editors Overview document.

In this topic:

Expanded Numeric Mask Mode

To enable the Numeric mask type, set the MaskProperties.MaskType property of the RepositoryItemTextEdit.Mask object to MaskType.Numeric. The mask itself should be specified using the MaskProperties.EditMask 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. In this case, the editor's value in edit and display modes will be the same. To customize the editor's display format, use the RepositoryItem.DisplayFormat property.

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 will not be able to enter a fractional part of a number, even if it's allowed by the editor's mask.

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

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

(EditValue = -3080.6).

Expanded See Also

How would you rate this topic?​​​​​​​