Description
A string defining an enhanced (or standard) edit mask. Note that this type is simply a "string" type, renamed to make it easier to document and search for within the documentation. Essentially this is what you need to know when defining edit masks.

Sample masks are given at the bottom of these notes, along with some specific notes relating to the IBObjects TIB_EditEnh deriviative.

IMPORTANT: No provision has been made for multi-byte character sets in this enhanced mask processing, not even when processing standard edit masks.

Parts of this are copied/summarised from the VCL online help to put all the details in one place. Differences have are specified in this description.

A mask consists of four fields with semicolons separating the fields (as opposed to the three of the standard VCL mask). The first part of the mask is the mask itself. The second part is the character that determines whether the literal characters of a mask are saved as part of the data. The third part of the mask is the character used to represent unentered characters in the mask while displayed in a control. The forth part of the mask represents the character to be used to represent unentered characters in the returned string.

NOTE: In eemNumeric mode, if the forth part of the mask definition is the zero character ("0") then mandatory entry mask positions (masked with a "0") are not enforced, since the returned value will contain a zero in that position anyway.


These are the special characters used in the first field of the mask

! Changed from the TMaskEdit An edit mask starts in left-justified data-entry mode (as you enter each character the cursor moves to the right). This character can be used to switch between left-justified and right-justified data-entry mode. In right-justified data entry the cursor stays where it is, and the characters move to the left - when the right-justified section is full the cursor automatically moves to the next section of the mask. There MUST be a literal character between a change from one justification to another and this literal will ALWAYS be returned with the resulting text regardless of the "save-literals" setting. (If the entire mask is right or left justified this does not matter.) If this literal character is input then the cursor will automatically jump to the next section avoiding the need to fill the section. (See the sample date entry mask.)

> All characters after a > character are converted to uppercase.

< All characters after a < character are converted to lowercase.

<> Disables case conversions.

\ The character that follows a \ character is a literal character.

L The L character requires an alphabetic character only in this position. For the US, this is A-Z, a-z.

l The l character permits only an alphabetic character in this position, but doesn't require it.

A The A character requires an alphanumeric character only in this position. For the US, this is A-Z, a-z, 0-9.

a The a character permits an alphanumeric character in this position, but doesn't require it.

C The C character requires an arbitrary character in this position.

c The c character permits an arbitrary character in this position, but doesn't require it.

0 The 0 character requires a numeric character only in this position.

9 The 9 character permits a numeric character in this position, but doesn't require it.

# The # character permits a numeric character or a plus or minus sign in this position, but doesn't require it.

: The : character represents the regional time separator value.

/ The / character represents the regional date separator value.

; The ; character is used to separate the FOUR fields of the mask.

_ The _ character automatically inserts spaces into the text.

~ New and ONLY in eemMaskEnh and higher modes. All characters after a ~ character are converted to propercase. (This only applies to keyboard input and NOT to assigned strings.)

] New and ONLY in eemMaskEnh and higher modes. I call this the "Prefix Literal". The literal character following this is ONLY displayed if there are masked characters (user input characters) preceding this value.

[ New and ONLY in eemMaskEnh and higher modes. I call this the "Postfix Literal". The literal character following this is ONLY displayed if there are masked characters (user input characters) following this value.

, New and ONLY in eemMaskEnh and higher modes. The , character represents the regional thousands separator value.

. New and ONLY in eemMaskEnh and higher modes. The . character represents the regional decimal separator value.

- New and ONLY in eemNumeric mode. The - character represents the position of the "negative" sign if it is required. No value is displayed if the represented value is positive. Note that input the the sign character can occur at any point in the data-entry and the control will automatically assign the sign value to its required position. (It should only occur once in the mask.)

+ New and ONLY in eemNumeric mode. The + character represents the position of the sign character which is always displayed, either as a negative or positive according to the represented value. Note that input the the sign character can occur at any point in the data-entry and the control will automatically assign the sign value to its required position. (It should only occur once in the mask.)

Examples using eemMask mode:

Telephone: !\(999\)000-0000;1;_
Social Security: 000\-00\-0000;1;_
Long Zip Code: 00000\-9999;1;_


Examples using eemMaskEnh mode:

Formatted text: ["ccc[-ccc[-ccc]";0;_
Password input: cccccccccccc;0;_


Examples using eemNumeric mode:

Currency: !\$-999],999],990!.00;0;0;0
Floating Point: !+999],999],999],990!.099[,999[,999;0;0;0
Date-Time Input: !90!/!90!/!0000!\ !90!:!00;0;_;0


Example using eemMaskList mode (list of standard edit masks):

setup a string list like this...
(C0) 0000 0000
00*=(C000) cccccccccccccccccccccccc
01*=(C00) 000 000
04*=(C000) 000 000
13*=C0 0000
18*=(C000) 000 000
19*=(C000) cccccccccccccccccccccccc
#*=Cccccccccccccccccccccccccccccc

then assign this to the Mask.MaskList property of the control at run-time. This will setup mask processing which dynamically changes according to the input. The first value in the list is the default (the mask used when no other match is found), subsequent lines should appear as test=mask, where the test value is checked against the input string using the IsMatch function from IB_Parse (an IBObjects unit). This comparison supports the use of wildcard characters in the comparison - hence the use of "*" at the end of test values in the example shown above.

Obviously all masks in the list must have compatible test values in order to function correctly. Checking for a match is done in the order that the list is defined and will stop at the first match found. If no match is found then the default mask is used.


Example using eemMaskEnhList mode (list of enhanced edit masks):

setup a string list like this...
00000[-99999;1;_
??????*=00000-00000;1;_

then assign this to the Mask.MaskList property of the control at run-time. This is like the previous example except that the mask list supports enhanced mask options.


NOTE: TMaskEnh has a function called "SetMaskEx" and TCustomEditEnh and its derivatives have a function called "SetEditMaskEx" which take a single string parameter. These functions can be used to set both the mask and the mode in one hit from a single string input parameter. Different modes are identified using prefix values like "::SM::".

Examples:

Disable mask processing (eemNone mode)
CustomEditEnh.SetEditMaskEx( '::NO::' );

Install a standard mask (eemMask mode)
CustomEditEnh.SetEditMaskEx( '::SM::000\-00\-0000;1;_' );

Install an enhanced mask (eemMaskEnh mode)
CustomEditEnh.SetEditMaskEx( '::EM::["ccc[-ccc[-ccc]";0;_' );

Install an standard mask list (eemMaskList mode)
CustomEditEnh.SetEditMaskEx( '::SL::"CC\-CC;1;_","AB*=CC\$CC;1;_"' );
(ie. The supplied string is read into a string list as "CommaText", see TStrings for details.)

Install an numeric mask (eemNumeric mode)
CustomEditEnh.SetEditMaskEx( '::NM::!\$-999],999],990!.00;0;0;0' );


TIB_EditEnh and TIB_CustomEditEnh - The IBObjects derivatives.

The only way of setting an edit mask for an IBO control is to set the mask value in the EditMask list of IB_Connection or IB_Dataset. The EditMask list properties should be entered in the form...

FieldName1=EditMask1
FieldName2=EditMask2
etc

The enhanced masks should be entered with the appropriate mode prefix string, for example...

MyNumericField=::NM::!\$-999],999],990!.00;0;0;0

If no mode prefix is found then the mask will be interpretted as a standard mask (making the implementation compatible with existing installations).

Notice that these strings are the same form as passed to the SetEditMaskEx function described above - because that is the function used to assign these masks to the control by IBO.