SetMask

Description

Sets the edit mask and edit mask datatype for an EditMask control.

Applies to

EditMask controls

Syntax

editmaskname.SetMask ( maskdatatype, mask )

Argument

Description

editmaskname

The name of the EditMask for which you want to specify the edit mask.

maskdatatype

A MaskDataType enumerated datatype indicating the datatype of the mask. Values are:

  • DateMask!

  • DateTimeMask!

  • DecimalMask!

  • NumericMask!

  • StringMask!

  • TimeMask!

mask

A string whose value is the edit mask.


Return value

Integer.

Returns 1 if it succeeds and -1 if an error occurs. If any argument's value is null, SetMask returns null.

Usage

In an edit mask, a fixed set of characters represent a type of character that the user can enter. In addition, punctuation controls the format of the entered value. Each mask datatype has its own set of valid characters.

For example, the following is a mask of type string for a telephone number. The EditMask control displays the punctuation (the parentheses and dash). The pound signs represent the digits that the user enters. The user cannot enter any characters other than digits.

(###) ###-####

For help in specifying a valid mask, see the Edit Mask Style dialog box for an EditMask control in the Window painter. A ListBox in the dialog box shows the meaning of the special mask characters for each datatype, as well as masks that have already been defined.

If you are specifying the mask for a number, the format must use U.S. notation. That is, comma represents the thousands delimiter and a period represents the decimal place. At runtime, the locally correct symbols are displayed.

You cannot use SetMask to change the maskdatatype if the DropDownCalendar, Spin, or UseCodeTable properties of the EditMask control are set to true. If any of these properties is set to true, set the property value to false before calling SetMask, then reset the value to true.

You cannot use color for edit masks as you can for display formats.

Examples

These statements set the mask for the EditMask password_mask to the mask in pword_code. The mask requires the user to enter a digit followed by four characters of any type:

string pword_code
pword_code = "#xxxx"
password_mask.SetMask(StringMask!, pword_code)

This statement sets the mask for the EditMask password_mask to a 5-digit numeric mask:

password_mask.SetMask(NumericMask!, "#####")