[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]Input Mask
       Mask Type: Numeric
       Mask Type: Date-time
       Mask Type: Extended Regular Expressions
       Mask Type: Simple
       Mask Type: Simplified Regular Expressions
     [Expand]Format and Parse Editor Values
     [Expand]Editor Buttons
     [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
    Templated ListBox Controls
  [Expand]Ribbon, Bars and Menu
  [Expand]Application UI Manager
  [Expand]Docking Library
  [Expand]Data Grid
  [Expand]Vertical Grid
  [Expand]Property 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]Sunburst Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[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)

Input Mask

Expanded Overview

Text editors support input masks. An input mask restricts the data input and formats data output. For example, a text editor should only accept phone numbers or date-time values in 24-hour format.

Note

Run the XtraEditors demo to try out input masks.

All TextEdit descendants support input masks except LookUpEdit, GridLookUpEdit, TreeListLookUpEdit, MemoEdit, MemoExEdit, and ImageComboBoxEdit controls.

Expanded Specify Input Mask in Designer

Use Mask Editor to specify an input mask. To invoke the editor, click the RepositoryItemTextEdit.Mask property's ellipsis button in the Properties window. The editor allows you to apply a predefined mask or create a custom mask.

You can also specify mask settings in Visual Studio's Properties window.

Expanded Mask Expression and Mask Type

The RepositoryItemTextEdit.Mask property provides access to a MaskProperties class instance that specifies an input mask. Use the MaskProperties.EditMask and MaskProperties.MaskType properties to specify the mask expression and type (the expression is parsed according to the type). The following table lists available types.

Mask Type

Use Case

Description

Example (the result depends on the current culture)

MaskType.Simple

An editor should accept values in a fixed format without alternatives. For instance, phone numbers and alpha-numeric sequences.

The mask expression can contain meta, special, and literal characters. See Mask Type: Simple for more information.

  • (999)000-00-00

MaskType.Numeric

An editor should accept numeric values in a specific format.

Use the standard numeric .Net format to specify mask expressions. See Mask Type: Numeric for more information.

  • c

  • # ##0.00 $;(# ##0.00 $)

MaskType.DateTime, MaskType.DateTimeAdvancingCaret

An editor should accept date-time values in a specific format.

Use the standard date-time .Net format to specify mask expressions. See Mask Type: Date-time for more information.

  • D

  • yyyy-MMM-d, HH:mm:ss

MaskType.RegEx

  • An editor should accept values with a custom range of characters at a specific position.
  • An editor should accept values of indeterminate length.
  • An editor should accept values in one of several formats.
  • An editor should support the auto-complete feature.

Use the extended regular expression syntax to specify mask expressions. This syntax is similar to the syntax defined in the POSIX ERE specification. See Mask Type: Extended Regular Expressions for more information.

  • ((\+\d)?\(\d{3}\))?\d{3}-\d\d-\d\d

MaskType.Regular

  • An editor should accept values with a custom range of characters at a specific position.
  • An editor should accept values of indeterminate length.

Use the simplified regular expression syntax to specify mask expressions. See Mask Type: Simplified Regular Expressions for more information.

Note

This type supports backward compatibility with XtraEditors version 2. We recommend you use MaskType.RegEx type instead.

  • [0-9A-F]*

MaskType.None

An editor should not provide a masked input.

The input mask is disabled.

The code below shows how to enable the long date format.

Expanded Options

The MaskProperties class also contains the following options (depending on the mask type):

Option MaskType.DateTime MaskType.Numeric MaskType.Simple MaskType.Regular MaskType.RegEx
BeepOnError
SaveLiteral
IgnoreMaskBlank
PlaceHolder
ShowPlaceHolders
AutoComplete

Input Mask as Output Format

The RepositoryItem.DisplayFormat property specifies how to format the editor's value when it is not focused. Enable the MaskProperties.UseMaskAsDisplayFormat setting to use the input mask as an output format.

BeepOnError Option

Set the MaskProperties.BeepOnError property to true to play the beep system sound when a user enters an invalid character. For example, a user enters a letter in an editor that accepts numbers only.

SaveLiteral Option

The MaskProperties.SaveLiteral property specifies whether the text editor's value comprises mask literals. For example, an editor accepts phone numbers in the specified format and the user enters (555)123-45-67. If this option is enabled, the editor's BaseEdit.EditValue property equals (555)123-45-67; otherwise, the property equals 5551234567.

PlaceHolder and ShowPlaceHolders Options

Use the MaskProperties.PlaceHolder property to change the default _ placeholder. Placeholders can be hidden for the RegEx type with the MaskProperties.ShowPlaceHolders property.

The following images show an empty text editor whose mask is set to the CODE-\d{3}-NO-\d{3} regular expression. In the first image, placeholders are shown. In the second image, placeholders are hidden.

IgnoreMaskBlank Option

The MaskProperties.IgnoreMaskBlank property specifies whether the editor can lose focus if its value is not completely entered. If the setting is enabled, the editor can only lose focus if the user completes the value or discards the changes. Use the BaseEdit.InvalidValue event to show an error message.

AutoComplete Option

The MaskProperties.AutoComplete property specifies auto-complete mode.

Mode

Description

Example

AutoCompleteType.Strong, AutoCompleteType.Default

The editor completes the value by one character at a time.

If the mask expression is \R{MonthNames}, the editor accepts month names. When the user enters 'M', the editor automatically adds 'a' because March and May start with 'Ma'.

Then, if the user types 'r', the editor automatically completes the value with 'March'.

AutoCompleteType.Optimistic

The editor completes the value at once. The default letter is 'a', the default number is '0'.

  • The mask expression is \R{MonthNames}. If the user enters 'M', the editor automatically completes the value with 'May' since it is the shortest variant between March and May.

  • The editor accepts phone numbers in the \d{3}-\d{2}-\d{2} format. If the user enters '1', the editor automatically fills in all other places with '0'.

Expanded See Also

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