Mask

Applies to

EditMask controls

Description

The Mask property controls the characters the user can enter in the control and also the formatting of the characters. You must use special characters to define the mask, depending on the mask type defined with the MaskDataType property.

PowerBuilder supports six mask types:

DateMask!
DateTimeMask!
DecimalMask!
NumericMask!
StringMask!
TimeMask!

Characters that have special significance for each mask type display in the Mask drop-down list. Characters that do not have special meaning for the format appear as is in the EditMask control.

For most mask types, the special characters you can use in a mask are the same as those you can use in a display format. For more information about using each kind of display format, see Chapter 4, “About Display Formats and Scrolling.” For more information about defining display formats, see the User’s Guide.

The special characters you can use in string edit masks are different from those you can use in string display formats.

**Table 3-2: Special characters for string edit masks**
Character	Meaning
!	Uppercase – displays all characters with letters in uppercase
^	Lowercase – displays all characters with letters in lowercase
#	Number – displays only numbers
a	Alphanumeric – displays only letters and numbers
X	Any character – displays all characters

If you use the “#” or “a” special characters in a mask, then Unicode characters, spaces, and other characters that are not alphanumeric do not display.

Usage

In a painter

To specify an edit mask:

Display the Mask tab page of the control’s Properties view.
Select the mask datatype from the MaskDataType drop-down list.
Type the mask characters in the Mask field, or click the right arrow at the end of the Mask field and select one or more of the mask character examples displayed in the pop-up menu.

The pop-up menu examples change based on the mask datatype you selected in the MaskDataType list.

In scripts

The Mask property takes a string value and can be used to obtain the value of a mask. It cannot be used to set the value.

The following example uses the SetMask function to set the datatype and string format for a mask, and then uses the Mask property to obtain the value of the string format. The mask specifies that the first letter in the string is displayed in uppercase and the next nine characters in lowercase. If the string has more than ten characters, they do not display:

string ls_mask

em_1.SetMask(StringMask!, '!^^^^^^^^^')
ls_mask = em_1.Mask