TMaskEdit

A TMaskEdit is a control with a single line of editable text that has to fit to a predefined 'EditMask'. It is available from the Additional tab of the Component Palette.

The EditMask property

The EditMask consist of 3 fields, each separated by the MaskFieldSeparator character (by default a semicolon (';')).

Field	Type	Meaning	Required
Actual mask	String	The actual pattern to which the text has to fit	Yes
MaskSave	Char	Controls wether the Text property contains the literals in the actual mask. A value other than '0' means literals will be included.	No
SpaceChar	Char	The character shown in the TMaskEdit when left blank. Defaults to '_'	No

The actual mask is formed with a pattern of characters with the following meaning:

Type	Character	Possible input by user	Delphi compatibility
cMask_SpecialChar	\	after this you can set an arbitrary char (e.g. for unit like 'P\a' => 'Pa')
cMask_LowerCase	<	after this the chars is in lower case
cMask_UpperCase	>	after this the chars is in upper case. Notice that the sequence <> will end enforcing lower- or uppercase.
cMask_Letter	l	only a letter but not necessary
cMask_LetterFixed	L	only a letter (arbitrary!)
cMask_AlphaNum	a	an alphanumeric char (['A'..'Z','a..'z','0'..'9']) but not necessary
cMask_AlphaNumFixed	A	an alphanumeric char (arbitrary!)
cMask_AllChars	c	any Utf8 char but not necessary
cMask_AllCharsFixed	C	any Utf8 char, but NOT SpaceChar
cMask_Number	9	only a number but not necessary [('0'..'9'])
cMask_NumberFixed	0	only a number (arbitrary!)
cMask_NumberPlusMin	#	only a number [('0'..'9']) or '+' or '-', but not necessary
cMask_HourSeparator	:	automatically put the hour separator char
cMask_DateSeparator	/	automatically put the date separator char
cMask_Hex	h	a hexadecimal character but not necessary	Lazarus extension, not supported by Delphi
cMask_HexFixed	H	a hexadecimal character	Lazarus extension, not supported by Delphi
cMask_Binary	b	a binary character but not necessary	Lazarus extension, not supported by Delphi
cMask_BinaryFixed	B	a binary character	Lazarus extension, not supported by Delphi
cMask_SetStart	[	Start of a set (if EnableSets = True)	Lazarus extension, not supported by Delphi
cMask_SetEnd	]	End of a set (if EnableSets = True)	Lazarus extension, not supported by Delphi
cMask_SetNegate	!	Negates a set (if it is the first character inside the given set)	Lazarus extension, not supported by Delphi
cMask_SetOptional	|	Makes the set optional, so a blank is accepted (if it is the first character inside the given set, and the set is not negated)	| Lazarus extension, not supported by Delphi
cMask_NoLeadingBlanks	!	Trim leading blanks, otherwise trim trailing blanks from the data

Avoiding Exceptions upon validation

When the user leaves the TMaskEdit (or presses Enter) the control validates the input against the EditMask.
By default, if validation fails, an EDBEditError exception will be raised.
If you want to handle this exception, you'll need to do this in the Application's OnException event.
You can avoid exceptions on validation if you set the ValidationErrorMode property to mvemEvent and handle the validation error in the TMaskEdit's OnValidationError event.
Notice that this is a Lazarus extension of TMaskEdit and it is not Delphi compatible.

Sample EditMask files

The property editor for TMaskEdit.EditMask supports the loading of sample files.
Delphi sample editmask files (.dem) were already supported for a long time and in Lazarus 4.0 support for Lazarus sample editmask files (.lem) was added.
The latter has a more relaxed syntax, where whitespace is non-significant (in other words: it will be ignored).
For copyrigth reasons Lazarus does not distribute sample editmask files itself.

Syntax of sample EditMask files

Sample EditMask files are plain text files, where each line defines a sample editmask.
Each line consists of 3 fields separated by a pipe symbol. In Delpi sample files (*.dem) each pipe symbol must be preceeded and followed by a space.
Lines starting with // will be ignored. You can use this feature to add comments to your sample editmask file(s).
Notice that Lazarus assumes the file is UTF-8 encoded.

Fieldname	Meaning
Caption	The name of the sample editmask as displayed in the property editor
Example	Example text applied to the editmask (*)
EditMask	Sample editmask

• When applying the example text, the sample editmask's MaskSave and SpaceChar fields will be ignored (and set to False and a space char (#32) respectively). This is done for Delphi compatibility.
  Consider the following line in a sample file:
  IPv4 value | 128255255032 | !999.999.999.999;1;_
  This will show "IPv4 value" as caption and "128.255.255.032" as an example in the property editors listbox (without the quotes obviously).

See also

• TMaskEdit doc
• TEdit - A basic field
• TLabeledEdit - An edit field like a TEdit with a label
• TSpinEdit - An edit field for integers defined numbers range limits
• TFloatSpinEdit - An edit field for tiles floating-point numbers with defined numbers range limits
• TEditButton - An edit field like a TEdit with an attached button as a TSpeedBtn
• TFileNameEdit - An edit field with attached TOpenDialog, to enter a file name
• TDirectoryEdit - An edit field with attached TSelectDirectoryDialog, to enter a file path
• TDateEdit - An edit field with attached TCalendarDialog (calendar), to enter a date
• TCalcEdit - An input field with attached TCalculatorDialog (Calculator), to enter a number
• TTIEdit - An RTTI capable input field

---

From the Free Pascal wiki, page "TMaskEdit", as it stood on 2024-05-20 after a change by Bart, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's Licensing page. If you have concerns about this material, message the admin.