FarPoint's Input Pro Product Tour

The fpMask control makes it easy for the user to provide specific character and numeric data. By defining a mask, you can specify the characters allowed for every position in the control.

A mask can provide visual cues about the type of data to provide, such as pound signs and dashes for a social security number. You can tailor your mask to the type of data that the user should provide by defining your own mask characters. You can also add buttons to an fpMask control to customize user interaction.

Creating an Input Mask | Creating User-Defined Mask Characters | Customizing User Entry | Providing Buttons | Working with the Clipboard | Validating Mask Data

Back to Top

Creating an Input Mask

An input mask consists of a string of predefined or user-defined mask characters and literals. Each mask character represents a position in which the user can type a character. Different mask characters allow certain types of input.

The following predefined mask characters are available:

	Character	Definition
	#	Allows numbers only
	&	Allows any character
	?	Allows letters only
	A	Allows numbers and letters
	U	Allows only letters and makes them uppercase
	L	Allows only letters and makes them lowercase
	H	Allows hexadecimal values (0-9, A-F only)
	\	Defines a predefined mask character as a literal
	0-9	Reserved for user-defined mask characters defined using the MaskChar property

A literal is a character or symbol that the user cannot type over. For example, the first figure above shows an fpMask control containing a mask for a telephone number. In this example, the parentheses and the dash are literals; they help cue the user about what kind of data to enter. The example also uses a custom prompt character (#) to further cue the user.

Creating User-Defined Mask Characters
You can create up to 10 sets of user-defined mask characters to use in your fpMask control. Use the array index value in your mask definition to specify where to use your defined sets. You can exclude the use of certain characters. To do so, place a tilde character (~) before the characters in your set definition. All the subsequent characters are excluded from the set of valid characters. The following code defines three mask characters, one of which excludes the use of some numbers. fpMask1.MaskChar(0)="12345ABC" fpMask1.MaskChar(1)="~12345" fpMask1.MaskChar(9)="XYZ" The following code defines a mask using the defined mask characters' array index values. The second line of the following code provides a valid string for the fpMask control. fpMask1.Mask="100009" fpMask1.Text="A1234X"

Customizing User Entry
If the fpMask control has a defined mask, by default, the control validates data as it is received, either as it is typed by the user, or when it is assigned in code, read from a database, or pasted into the control. If a character is supplied by the user typing or by pasting that is not valid for the control, the control does not accept the character, and a UserError event occurs. If a character is supplied from a database or from code, the character is accepted, but the UserError event still occurs. You can specify that the control beeps when it receives an invalid character. You can specify that data the user types or pastes into the control is not validated as it is typed or pasted. You can also specify that data received in code or from a database is loaded into the control by the control ignoring invalid characters and only placing available valid characters into the control. You can allow the user to type more than the maximum number of characters allowed in the control without causing a UserError event. The value supplied to the fpMask control can contain letters, numbers, and symbols. For a mask created with the Mask property, which characters are considered invalid depends on the position of the character and the definition of its corresponding mask character. If any character conflicts with the mask, the value is considered invalid. For example, with a telephone number mask such as "(###) ###-####", all characters other than numbers are invalid.

Providing Buttons
The fpMask control can display buttons to let the user quickly change the value in the control without typing. You can choose which type of buttons to display. Unlike other formatted edit controls, the fpMask control does not have a default button style associated with it. Therefore, you must provide code in the ButtonHit event to assign behavior to the buttons.

Working with the Clipboard
The fpMask control can provide literal characters that format the mask value. For example, a social security number includes hyphens that separate parts of the number, which you might want to display in the mask. Literal characters can be included when data is cut or copied to the Clipboard. You can specify whether literal characters in the input mask are sent to the Clipboard during cut or copy operations by setting the ClipMode property.

Validating Mask Data
NOTE: Be sure to read the Customizing User Entry* section above for information on validation of data while being entered by the user.* When the fpMask control loses the focus, it checks the value of the control to see whether it is valid. You can specify that incomplete values are invalid by setting the RequireFill property to True. If an invalid value (incomplete or containing invalid characters) is received, an InvalidData event occurs after the control loses the focus. You can change the fpMask control's appearance to reflect that it has received invalid data. In addition, you can specify whether and how invalid data is displayed. You can specify whether the control allows the Null value. If the control allows the Null value as a valid value, the control is blank when it contains the Null value, and it displays as its background color the color specified by the NullColor property. Otherwise, the control displays the prompt characters for the mask.

fpMask Control

Have a question?

RSS Subscribe

SD Times 'TOP 100' Industry Innovator - Read the press release (pdf)

fpDoubleSingle Control

fpLongInteger Control