Editor.Mask Property (ExGrid)

Use the Mask property to filter characters during data input. Use the Mask property to control the entry of many types of formatted information such as telephone numbers, social security numbers, IP addresses, license keys etc. The Mask property has effect for the following edit types: DropDownType, SpinType, DateType, MaskType, FontType, PickEditType. The Numeric property specifies whether the editor enables numeric values only. Use the MaskChar property to change the masking character. The Mask property is composed by a combination of regular characters, literal escape characters, and placeholders, masking characters. The Mask property can contain also alternative characters, or range rules.

Starting from the version 8.0, the Mask property has been changed radically, to support more special characters, validation, float numbers, and so on.

For instance, the following input-mask ( ext-phone )

"!(999) 000 0000;1;;select=1,empty,overtype,warning=invalid character,invalid=The value you entered isn't appropriate for the input mask '<%mask%>' specified for this field."

indicates the following:

The pattern should contain 3 optional digits 999, and 7 required digits 000 0000, aligned to the right, !.
The second part of the input mask indicates 1, which means that all literals are included when the user leaves the field.
The entire field is selected when it receives the focus, select=1
The field supports empty value, so the user can leave the field with no content
The field enters in overtype mode, and insert-type mode is not allowed when user pressed the Insert key
If the user enters any invalid character, a warning tooltip with the message "invalid character" is displayed.
If the user tries to leave the field, while the field is not validated ( all 7 required digits completed ), the invalid tooltip is shown with the message "The value you entered isn't appropriate for the input mask '<%mask%>' specified for this field." The <%mask%> is replaced with the first part of the input mask !(999) 000 0000

The four parts of an input mask, or the Mask property supports up to four parts, separated by a semicolon (;). For instance, "`Time: `00:00:00;;0;overtype,warning=<fgcolor FF0000>invalid character,beep", indicates the pattern "00:00" with the prefix Time:, the masking character being the 0, instead _, the field enters in over-type mode, insert-type mode is not allowed, and the field beeps and displays a tooltip in red with the message invalid character when the user enters an invalid character.

Input masks are made up one mandatory part and three optional parts, and each part is separated by a semicolon (;). If a part should use the semicolon (;) it must uses the \; instead

The purpose of each part is as follows:

The first part (pattern) is mandatory. It includes the mask characters or string (series of characters) along with placeholders and literal data such as, parentheses, periods, and hyphens.
The following table lists the placeholder and literal characters for an input mask and explains how it controls data entry:
- #, a digit, +, - or space (entry not required).
- 0, a digit (0 through 9, entry required; plus [+] and minus [-] signs not allowed).
- 9, a digit or space (entry not required; plus and minus signs not allowed).
- x, a lower case hexa character, [0-9],[a-f] ( entry required )
- X, an upper case hexa character, [0-9],[A-F] ( entry required )
- A, any letter, digit (entry required).
- a, any letter, digit or space (entry optional).
- L, any letter (entry require).
- ?, any letter or space (entry optional).
- &, any character or a space (entry required).
- C, any character or a space (entry optional).
- >, any letter, converted to uppercase (entry required).
- <, any letter, converted to lowercase (entry required).
- *, any characters combinations
- { min,max } (Range), indicates a number range. The syntax {min,max} (Range), masks a number in the giving range. The min and max values should be positive integers. For instance the mask {0,255} masks any number between 0 and 255.
- [...] (Alternative), masks any characters that are contained in the [] brackets. For instance, the [abcdA-D] mask any character: a,b,c,d,A,B,C,D
- \, indicates the escape character
- ť, ( ALT + 175 ) causes the characters that follow to be converted to uppercase, until Ť( ALT + 174 ) is found.
- Ť, ( ALT + 174 ) causes the characters that follow to be converted to lowercase, until ť( ALT + 175 ) is found.
- !, causes the input mask to fill from right to left instead of from left to right.
Characters enclosed in double quotation ("" or ``) marks will be displayed literally. If this part should display/use the semicolon (;) character is should be included between double quotation ("" or ``) characters or as \; ( escape ).
The second part is optional and refers to the embedded mask characters and how they are stored within the field. If the second part is set to 0 ( default, exClipModeLiteralsNone ), all characters are stored with the data, and if it is set to 1 (exClipModeLiteralsInclude), the literals are stored, not including the masking/placeholder characters, if 2 (exClipModeLiteralsExclude), just typed characters are stored, if 3(exClipModeLiteralsEscape), optional, required, editable and escaped entities are included. No double quoted text is included.
The third part of the input mask is also optional and indicates a single character or space that is used as a placeholder. By default, the field uses the underscore (_). If you want to use another character, enter it in the third part of your mask. Only the first character is considered. If this part should display/use the semicolon (;) character is should be \; ( escape ) (MaskChar property)
The forth part of the input, indicates a list of options that can be applied to input mask, separated by comma(,) character.
The known options for the forth part are:
- float, indicates that the field is edited as a decimal number, integer. The first part of the input mask specifies the pattern to be used for grouping and decimal separators, and - if negative numbers are supported. If the first part is empty, the float is formatted as indicated by current regional settings. For instance, "##;;;float" specifies a 2 digit number in float format. The grouping, decimal, negative and digits options are valid if the float option is present.
- grouping=value, Character used to separate groups of digits to the left of the decimal. Valid only if float is present. For instance ";;;float,grouping=" indicates that no grouping is applied to the decimal number (LOCALE_STHOUSAND)
- decimal=value, Character used for the decimal separator. Valid only if float is present. For instance ";;;float,grouping= ,decimal=\," indicates that the decimal number uses the space for grouping digits to the left, while for decimal separator the comma character is used (LOCALE_SDECIMAL)
- negative=value, indicates whether the decimal number supports negative numbers. The value should be 0 or 1. 1 means negative numbers are allowed. Else 0 or missing, the negative numbers are not accepted. Valid only if float is present.
- digits=value, indicates the max number of fractional digits placed after the decimal separator. Valid only if float is present. For instance, ";;;float,digits=4" indicates a max 4 digits after decimal separator (LOCALE_IDIGITS)
- password[=value], displays a black circle for any shown character. For instance, ";;;password", specifies that the field to be displayed as a password. If the value parameter is present, the first character in the value indicates the password character to be used. By default, the * password character is used for non-TrueType fonts, else the black circle character is used. For instance, ";;;password=*", specifies that the field to be displayed as a password, and use the * for password character. If the value parameter is missing, the default password character is used.
- right, aligns the characters to the right. For instance, "(999) 999-9999;;;right" displays and masks a telephone number aligned to the right
- readonly, the editor is locked, user can not update the content, the caret is available, so user can copy the text, excepts the password fields.
- inserttype, indicates that the field enters in insert-type mode, if this is the first option found. If the forth part includes also the overtype option, it indicates that the user can toggle the insert/over-type mode using the Insert key. For instance, the "##:##;;0;inserttype,overtype", indicates that the field enter in insert-type mode, and over-type mode is allowed. The "##:##;;0;inserttype", indicates that the field enter in insert-type mode, and over-type mode is not allowed.
- overtype, indicates that the field enters in over-type mode, if this is the first option found. If the forth part includes also the inserttype option, it indicates that the user can toggle the insert/over-type mode using the Insert key. For instance, the "##:##;;0;overtype,inserttype", indicates that the field enter in over-type mode, and insert-type mode is allowed. The "##:##;;0;overtype", indicates that the field enter in over-type mode, and insert-type mode is not allowed.
- nocontext, indicates that the field provides no context menu when user right clicks the field. For instance, ";;;password,nocontext" displays a password field, where the user can not invoke the default context menu, usually when a right click occurs.
- beep, indicates whether a beep is played once the user enters an invalid character. For instance, "00:00;;;beep" plays a beep once the user types in invalid character, in this case any character that's not a digit.
- warning=value, indicates the html message to be shown when the user enters an invalid character. For instance, "00:00:00;;;warning=invalid character" displays a "invalid character" tooltip once the user types in invalid character, in this case any character that's not a digit. The <%mask%> keyword in value, substitute the current mask of the field, while the <%value%> keyword substitutes the current value ( including the literals ). If this option should display/use the semicolon (;) character is should be \; ( escape )
- invalid=value, indicates the html message to be displayed when the user enters an inappropriate value for the field. If the value is missing or empty, the option has no effect, so no validation is performed. If the value is a not-empty value, the validation is performed. If the value is single space, no message is displayed and the field is keep opened while the value is inappropriate. For instance, "!(999) 000 0000;;;invalid=The value you entered isn't appropriate for the input mask '<%mask%>' specified for this field." displays the "The value you entered isn't appropriate for the input mask '...' specified for this field." tooltip once the user leaves the field and it is not-valid ( for instance, the field includes entities required and uncompleted ). The <%mask%> keyword in value, substitute the current mask of the field, while the <%value%> keyword substitutes the current value ( including the literals ). If this option should display/use the semicolon (;) character is should be \; ( escape ). This option can be combined with empty, validateas. The invalid option should be used, with the CauseValidateValue property on True, so the user can not leaves the field while it contains an invalid value.
- validateas=value, specifies the additional validation is done for the current field. If value is missing or 0 (exValidateAsNone), the option has no effect. The validateas option has effect only if the invalid option specifies a not-empty value. Currently, the value can be 1 (exValidateAsDate), which indicates that the field is validated as a date. For instance, having the mask "!00/00/0000;;0;empty,validateas=1,invalid=Invalid date!,warning=Invalid character!,select=4,overtype", indicates that the field is validate as date ( validateas=1 ).
- empty, indicates whether the field supports empty values. This option can be used with invalid flag, which indicates that the user can leave the field if it is empty. If empty flag is present, the field displays nothing if no entity is completed ( empty ). Once the user starts typing characters the current mask is displayed. For instance, having the mask "!(999) 000 0000;;;empty,select=4,overtype,invalid=invalid phone number,beep", it specifies an empty or valid phone to be entered.
- select=value, indicates what to select from the field when it got the focus. The value could be 0 ( nothing, exSelectNoGotFocus ), 1 ( select all, exSelectAllGotFocus ), 2 ( select the first empty and editable entity of the field, exSelectEditableGotFocus ), 3 ( moves the cursor to the beginning of the first empty and editable entity of the field, exMoveEditableGotFocus ), 4 ( select the first empty, required and editable entity of the field, exSelectRequiredEditableGotFocus ), 5 ( moves the cursor to the beginning of the first empty, required and editable entity of the field, exMoveRequiredEditableGotFocus ). For modes 2 and 4 the entire field is selected if no matching entity is found. For instance, "`Time:`XX:XX;;;select=1" indicates that the entire field ( including the Time: prefix ) is selected once it get the focus. The "`Time:`XX:XX;;;select=3", moves the cursor to first X, if empty, the second if empty, and so on
- leading=value, specifies whether the spaces or masking/placeholder (0,9) characters are replaced with giving value ( 0 if the value is missing ). This option has effect, only for DateType fields ( Editor.EditType property is DateType ), when the field is entering in edit mode, or the user selects a new date from the drop down calendar. For instance, "!99/99/9999;1;;empty,validateas=1,invalid=Invalid date\, for the input mask '<%mask%>'!,warning=Invalid character!,select=4,overtype,leading", having the cell's value on #1/1/2001# it displays 01/01/2001, instead 1/1/2001.
Experimental:
multiline, specifies that the field supports multiple lines.
rich, specifies that the field displays a rich type editor. By default, the standard edit field is shown
disabled, shows as disabled the field.

The following special characters are supported only in versions prior to version 8.0

Here's the list of all rules and masking characters:

# (Digit), Masks a digit character. [0-9]
x (Hexa Lower), Masks a lower hexa character. [0-9],[a-f]
X (Hexa Upper), Masks a upper hexa character. [0-9],[A-F]
A (AlphaNumeric), Masks a letter or a digit. [0-9], [a-z], [A-Z]
? (Alphabetic), Masks a letter. [a-z],[A-Z]
< (Alphabetic Lower), Masks a lower letter. [a-z]
> (Alphabetic Upper), Masks an upper letter. [A-Z]
* (Any), Mask any combination of characters.
\ (Literal Escape), Displays any masking characters. The following combinations are valid: \#,\x,\X,\A,\?,\<,\>,\\,\{,\[
{nMin,nMax} (Range), Masks a number in a range. The nMin and nMax values should be numbers. For instance the mask {0,255} will mask any number between 0 and 255.
[...] (Alternative), Masks any characters that are contained by brackets []. For instance, the [abcA-C] mask any character: a,b,c,A,B,C

The following VB sample adds a mask for IP addresses:

With Grid1
    With .Columns.Add("Mask")
        With .Editor
            .EditType = EditTypeEnum.MaskType
            .Mask = "{0,255}\.{0,255}\.{0,255}\.{0,255}"
        End With
    End With
    .Items.AddItem "193.226.40.161"
End With

The following VB sample masks a phone number:

With Grid1
    With .Columns.Add("Mask")
        With .Editor
            .EditType = EditTypeEnum.MaskType
            .Mask = "(XXX) - XXX XXXX"
        End With
    End With
    .Items.AddItem "(095) - 889 1234"
End With

The following C++ adds a mask editor to filter characters while entering a phone number:

#include "Items.h"
#include "Editor.h"
COleVariant vtMissing; V_VT( &vtMissing) = VT_ERROR;
CItems items = m_grid.GetItems();
CEditor editor = items.GetCellEditor( COleVariant( items.GetFirstVisibleItem() ), COleVariant( long(0) ) );
editor.SetEditType( 8 /*MaskType*/ );
editor.SetMask("(###) ### - ####");

The following VB.NET adds a mask editor to filter characters while entering a phone number:

With AxGrid1.Items
    With .CellEditor(.FirstVisibleItem, 0)
        .EditType = EXGRIDLib.EditTypeEnum.MaskType
        .Mask = "(###) ### - ####"
    End With
End With

The following C# adds a mask editor to filter characters while entering a phone number:

EXGRIDLib.Items items = axGrid1.Items;
EXGRIDLib.Editor editor = items.get_CellEditor(items.FirstVisibleItem, 0);
editor.EditType = EXGRIDLib.EditTypeEnum.MaskType;
editor.Mask = "(###) ### - ####";

The following VFP adds a mask editor to filter characters while entering a phone number:

with thisform.Grid1.Items
	With .CellEditor(.FirstVisibleItem, 0) 
		.EditType = 8 && MaskType
		.Mask = "(###) ### - ####"
	EndWith
endwith

		Type	Description
		String	A string expression that defines the editor's mask.