Defines classes, types, and constants used to implement a masked edit control.

maskedit.pp implements an masked edit control which can be used to format, validate, or obscure the text entered in the control. The following components are added to the Lazarus IDE component palette:

Additional Tab

TMaskEdit

maskedit.pp is part of the Lazarus Component Library (LCL).

After this you can set an arbitrary char. After this the chars are in upper case. After this the chars are in lower case. Can contain an optional letter only. Must contain a letter only. An optional alphanumeric character. ['A'..'Z','a..'z','0'..'9'] A required alphanumeric character. ['A'..'Z','a..'z','0'..'9'] An optional UTF-8 character. Any UTF-8 character in the range #32 to #255 A required UTF-8 character. Any UTF-8 character in the range #32 to #255 An optional numeric character. In the range '0' to '9' A required numeric character. In the range '0' to '9' An optional numeric or sign character. Includes the characters: 0,1,2,3,4,5,6,7,8,9,+, and - Inserts the hour separator char. Inserts the date separator character. An optional hexadecimal character. (['0'..'9','a'..'f']). A Lazarus extension, not supported in Delphi. A required hexadecimal character. (['0'..'9','a'..'f']). A Lazarus extension, not supported in Delphi. An optional binary character. ['0'..'1']. A Lazarus extension, not supported in Delphi. A required binary character. ['0'..'1']. A Lazarus extension, not supported in Delphi. Causes leading blanks to be trimmed from the value. Trailing blanks are trimmed by default. Indicates the start of a set definition.

Uses notation like:

[abc]: Set with the characters 'a'. 'b', and 'c'.
[a-z]: Equivalent to the ['a'..'z'] notation in Pascal.

In the current implementation, sets are always case-sensitive and can contain only ASCII characters.

Indicates the end of a set definition. Negates the following set definition.

Common usage:

[!abc]: Any character not in the set ['a','b','c'].

Indicates a set of optional characters allowed for a position in a mask.

Common usage:

[|abc]: Character must be 'a', 'b', 'c' or a blank (space). Only interpreted as such if set is not negated using cMask_SetNegate.

Indicates that the character set definition uses a range of character values. Represents a blank character value in a mask. Can be changed at run-time. Delimiter used between fields in a mask. Can be changed at run-time. Represents a character that is not stored in a mask. Can be changed at run-time. Enumeration with values representing mask character types.

TMaskType is an enumerated type which contains values representing mask character types used in TCustomMaskEdit and TMaskEdit. Mask character types control the letters, numbers, literals, space characters, and trimming options allowed for each position in a masked edit control.

TMaskType values are stored in the TInternalMask type, and used in the implementation of TCustomMaskEdit.

Character is a literal. Character is an optional numeric value 0..9. Character is a required numeric value 0..9. Character is an optional numeric value 0..9, +, - Character is an optional alphabetic value. Character is a required alphabetic value. Character is an optional uppercase alphabetic value. Character is an optional lowercase alphabetic value. Character is a required uppercase alphabetic value. Character is a required lowercase alphabetic value. Character is an optional alphabetic or numeric value. Character is a required alphabetic or numeric value. Character is an optional uppercase alphabetic or numeric value. Character is an optional lowercase alphabetic or numeric value. Character is a required uppercase alphabetic or numeric value. Character is a required lowercase alphabetic or numeric value. Any optional UTF-8 character. Any required UTF-8 character. Any optional uppercase UTF-8 character. Any optional lowercase UTF-8 character. Any required uppercase UTF-8 character. Any required lowercase UTF-8 character. Character is the time separator character. Character is the date separator character. Character is an optional hexadecimal digit. Lazarus extension, not supported by Delphi. Character is a required hexadecimal digit. Lazarus extension, not supported by Delphi. Character is an optional uppercase hexadecimal digit. Lazarus extension, not supported by Delphi. Character is an optional lowercase hexadecimal digit. Lazarus extension, not supported by Delphi. Character is a required uppercase hexadecimal digit. Lazarus extension, not supported by Delphi. Character is a required lowercase hexadecimal digit. Lazarus extension, not supported by Delphi. Character is an optional binary value 0..1. Lazarus extension, not supported by Delphi. Character is a required binary value 0..1. Lazarus extension, not supported by Delphi. Optional character must be in the defined set or space. Lazarus extension, not supported by Delphi Required character must be in the defined set. Required character must NOT be in the defined set. Represents the type and literal used for a character in an edit mask.

TIntMaskRec is a record type with members that represent the types and literal used for a character in TCustomMaskEdit. TIntMaskRec instances are stored in the TInternalMask array type, and used in the implementation of the TCustomMaskEdit control.

Identifies the type for the mask character. Contains the literal displayed for the mask character. Array type used to represent edit mask symbols in TCustomMaskEdit.

TInternalMask is an array type which contains up to 255 TIntMaskRec values representing mask characters used in a TCustomMaskEdit control. It is used to implement internal members in TCustomMaskEdit, and realized using its EditMask property.

Controls how the value in a masked edit control is trimmed.

TMaskEditTrimType is an enumerated type with values that control if / how the text in TCustomMaskEdit is trimmed.

Trims leading spaces from the value for a masked edit control. Trims trailing spaces from the value for a masked edit control; this is the default action in TCustomMaskEdit. Represents the action taken for an error in TMaskEdit validation.

TMaskEditValidationErrorMode is an enumerated type with values that represent the action taken when a error occurs while validating the value in TCustomMaskEdit and descendants. It is the type used to implement the ValidationErrorMode property in TCustomMaskEdit.

Causes an exception to be raised for a validation error in TMaskEdit. Causes the OnValidationError event handler to be signalled for a validation error in TMaskEdit. Exception class raised for an error in a masked edit control.

Raised in the TCustomMaskEdit.ValidateEdit method when exiting the edit control where its text is in an invalid state for its edit mask.

Despite the name, this exception has nothing to do with a database error. Exception type raised for an invalid mask value in an edit mask.

Indicates that the content in EditMask is not a valid edit mask expression. Raised when a value is assigned to the EditMask property. Generally indicates that an invalid set declaration has been used in the edit mask.

Ancestor for UTF-8 exceptions.

EInvalidUtf8 is an Exception descendant that implements the ancestor for exceptions that occur for UTF-8-encoded content.

Exception raised when an error occurs while setting a UTF-8 Code Point in a String.

EInvalidCodePoint is an EInvalidUtf8 descendant that implements the Exception raised when an error occurs while setting a UTF-8 Code Point in a String. The exception message contains the constant value in SInvalidCodePoint.

Used in the SetCodePoint routine in the implementation section for the unit.

Message displayed in the EInvalidCodePoint exception. Exception message used when a position in the internal mask is not valid. Exception message used when an invalid mask character is found. Exception message used when an unclosed set is found in an edit mask. Exception message used when a mask character not in the ASCII character set is used. Exception message used when an empty set is specified in an edit mask. Exception message used when more than one set range is used in an edit mask. The base class for TMaskEdit.

TCustomMaskEdit is a TCustomEdit descendant, and the base class for TMaskEdit. TCustomMaskEdit provides an Edit box with masking features for characters displayed (or hidden) in the control.

FOR ANYONE WHO CARES TO FIX / ENHANCE THIS CODE:

Since we want total control over anything that is done to the text in the control, we have to take into consideration the fact that currently we cannot prevent cutting/pasting/clearing or dragging selected text in the control. These operations are handled by the OS, and text is changed before we can prevent it. Not all widgetsets currently handle the messages for cut/paste/clear. Actually, we would like to have a LM_BEFORE_PASTE (etc.) message... If we allow the OS to cut/clear/paste etc. A situation can occur where mask-literals in the control are changed to random characters (which cannot be undone), or text is shorter or larger than the editmask calls for, which again cannot be undone.

So, as a horrible hack, I decided to only allow changing the text if we coded this change ourself. This is done by setting the FChangeAllowed field to True before any write action (in RealSetTextWhileMasked() ). We try to intercept the messages for cut/paste/copy/clear and perform the appropriate actions instead. If this fails, then in TextChanged we check and will see that FChangeAllowed = False and we will undo the changes made.

To make this undo possible, it is necessary to set FCurrentText every time you set the text in the control! This is achieved in RealSetTextWhileMasked() only.

It is unsafe to make a call to RealSetText unless done so via RealSetTextWhileMasked!!!

Bart Broersma, January 2009

Real mask inserted. Actual internal mask. Length of the internal mask. First position where user can enter text (1-based). Save mask as part of the data? Trim leading or trailing spaces in GetText. Character used for space characters (default value is '_'). FCurrentText is our backup. See the notes for TCustomMaskEdit. Text when user enters the control, used for Reset(). Current caret position (0-based). Indicates if text can be changed by the OS (copy/cut/paste/clear via the context menu). Value for the text set in the form designer (must be handled in Loaded). EditMask set in the form designer (must be handled in Loaded). Flag which indicates if the control value is being assigned for the first time. Flag used in DoEnter. Set to mvemException by default. True when the internal mask has been saved in DisableMask. Saved internal mask. Length of the saved internal mask. Used with FInRealSetTextWhileMasked to determine real value for Modified. Used with FTextChangedBySetText to determine real value for Modified. Fills the specified mask with Null characters (decimal 0). Mask updated in the method. Set to zero (0) to indicate that the mask is empty. Appends the specified mask character or literal to the internal mask in the control.

AddToMask is an overloaded procedure used to append a mask character to the internal mask for the edit control. The overloaded variants allow the mask character to be specified as a TMaskedType enumeration value or a UTF-8-encoded character literal.

AddToMask increments the length counter for the internal mask, and stores the specified value in the TInternalMask instance. When ALiteral is used for the mask character, the TIntMaskRec.MaskType member is set to Char_IsLiteral. When AMaskType is used, the TIntMaskRec.Literal member is set to an empty string ('').

AddToMask is called when a new value is assigned to the EditMask property and the internal TInternalMask member is cleared and populated.

UTF-8 character literal appended to the mask for the edit control. Enumeration value representing the mask character class. Sets the value for the Modified property. Value for the property. Gets values in the internal FMask member. Sets the value for the EditMask property.

Re-initializes the internal TInternalMask instance with the mask character classes and literals used in the EditMask.

New value for the EditMask property. Parses set notation found in the EditMask for the control. Value examined in the method. Position for UTF-8 codepoint with the set notation in the specified value. Length of the value examined in the method. Set of characters found in the set notation. True if the set has a negate operator. True if the character position for the set is optional, False when it is required. Gets the value for the IsMasked property. Value for the property. Sets the value for the Modified property. New value for the property. Sets the value for the SpaceChar property. New value for the property. Sets the cursor position, and selects the character in the control.

SetCursorPos is a procedure used to set the cursor or current caret position in the edit control. An internal member contains the offset in the control where the cursor is positioned. The cursor position cannot exceed the length of the mask in the control.

No actions are performed in the method at design-time.

SetCursorPos is used in the implementation of methods which respond to keyboard or mouse navigation, or when the value in the control is changed and/or validated.

Selects the next character in the edit control.

SelectNextChar is a procedure used to move to and select the next character in the value for the edit control. Mask literals in the control value are skipped. SelectNextChar calls the SetCursorPos method to update the caret (or cursor) position for the control.

Used in the implementation of the KeyDown method.

Selects the previous character in the edit control.

SelectPrevChar is a procedure used to move to and select the previous character in the value for the edit control. Mask literals in the control value are skipped. SelectPrevChar calls the SetCursorPos method to update the caret (or cursor) position for the control.

Used in the implementation of the KeyDown method.

Selects the first character in the edit control.

SelectFirstChar is a procedure used to move to and select the first character in the edit control. SelectFirstChar sets the value for the internal member used to track the cursor (or caret) position, and calls SetCursorPos to update the cursor in the control.

Moves the caret to the last position in the edit control.

GotoEnd is a procedure used to set the caret (or cursor) to the last position in the edit control. GotoEnd updates the internal member used to track the cursor position, and calls the SetCursorPos method to apply the cursor position to the control.

Used in the implementation of the KeyDown method.

Moves to the next occurrence of the specified character in the value for the edit control.

JumpToNextDot is a procedure used to move to the next occurrence of the character in Dot in the mask for the edit control. Dot must be included in the mask, and must occur after the current cursor position. Dot must contain either a Period ('.') or Comma (',') character; no actions are performed in the method when Dot contains another character value.

If a mask contains both Period and Comma characters, only the first character can be accesses using the method. A mask literal cannot appear after the requested occurrence of Dot, and the next occurrence cannot be the last character in the mask.

The cursor position is set to the next character after the mask literal, when allowed. JumpToNextDot calls the SetCursorPos method to update the caret position in the edit control.

JumpToNextDot is used in the implementation of the HandleKeyPress method.

Mask literal to locate in the edit mask for the control. Indicates if any characters are currently selected in the edit control.

HasSelection is a Boolean function which indicates if any characters are currently selected in the edit control. The return value is True when GetSelLength returns a value greater than one (1).

True when characters are selected at the caret position. Returns True if more than one (1) character is selected in the value for the control.

Influences handling of the Backspace key. In addition, the InsertChar method will delete an extended selection prior to inserting a new character value.

True when the current selection in the control is more than one character. Indicates whether the mask value at the specified position is a mask literal.

IsLiteral is a Boolean function which indicates whether the Integer value in Index represents a mask literal which cannot be edited in the control.

The return value is False when the mask type for the character in Index is not one for the following TMaskType values:

Char_IsLiteral: A mask literal.
Char_HourSeparator: The time separator character.
Char_DateSeparator: The date separator character.

IsLiteral is used in the implementation of methods like SetEditMask, SetSpaceChar, SelectNextChar, SelectPrevChar, JumpToNextDot, and SetEditText.

True if the specified character is a mask literal. Character position examined in the method. Indicates whether the specified value is valid for the EditMask in the control.

Returns False if the length of Value does not match the length for the edit mask, or when a UTF-8 Code Point in Value is not valid for the edit mask.

True when the value is valid for the edit mask. Value examined in the method. Determines if a character in the control value is valid for the specified EditMask.

CharMatchesMask is a Boolean function used to determine if a character in the value for the control is valid for its EditMask. Ch contains the UTF-8 character examined in the method.

Position contains the offset into the EditMask for the mask character compared in the method. Position is in the range 1..MaxLength.

CharMatchesMask uses the internal TInternalMask instance to determine if the value in Ch matches the mask definition at the specified position. The return value is True when Ch contains a valid character value for the mask character type.

If an unrecognized mask character type is found in the in the EditMask, an EDBEditError exception is raised. It is not really a database exception; it's just an identifier, defined in this unit, with a confusingly unfortunate name.

CharMatchesMask is used in the implementation of the TextIsValid method.

Raises an EDBEditError exception if an invalid mask literal is used in the EditMask. True when the character value is valid for the corresponding position in the EditMask. Character value examined in the method. Offset into the edit mask for the character value. Clears a character which is not a literal at the specified Position.

For Delphi compatibility, only literals remain.

ClearChar checks the TMaskType value for the character at the specified Position. The return value contains the hour separator, date separator, or literal value used for the mask character. Date and time separators use values from the DefaultFormatSettings variable in the RTL.

All other character values are replaced with the character designated in the SpaceChar property.

Character displayed for a mask literal at the specified position. Position in EditMask examined in the method. Sets the text in the control when a mask is in use.

RealSetTextWhileMasked is a method used to set the Text in the control to the content specified in Value.

RealSetTextWhileMasked calls the inherited RealGetText to get the current value for the control. No actions are performed in the method when Value is the same as the current text assigned to the control.

RealSetTextWhileMasked set values in internal members used to protect against unhandled exceptions from an assigned OnChange event handler. This ensures that the control is not left in an "unsafe" state after changes to the text value.

RealSetTextWhileMasked calls the inherited RealSetText method to store Value in the Text for the control. Values in the internal members are reset prior to exiting from the method.

New value for the Text in the control. Inserts a single UTF-8 character at the current position for the cursor.

InsertChar is a procedure used to insert the specified UTF-8 character at the current position for the cursor.

Ch contains the UTF-8 character stored at the cursor (or caret) position. InsertChar calls CanInsertChar to determine if the value is valid for the mask character at the cursor position. If CanInsertChar returns False, the current selection in the control is deleted (done for Delphi compatibility).

If the character is valid for the mask position, any selected characters in the control are replaced with blank values by calling SetCodePoint with the value from ClearChar. SetCodePoint is also called to store Ch at the current position in the text value. RealSetTextWhileMasked is called to notify the control of the change to its Text value. SelectNextChar is called to advance the cursor position to the next available position in the control (when available).

InsertChar is used in the implementation of the HandleKeyPress method.

Character value inserted at the current cursor position. Indicates if the specified character can be inserted at a given position in the control.

The value in Ch is converted to the case required for the mask type (when needed), and compared to value(s) permitted for the mask type. The return value is True when Ch contains a value permitted for the TMaskType.

Special logic is used when Ch contains a Space (#32) character, and is being applied using Paste from Clipboard. Delphi allows the Space character during Paste - even when it is invalid for the mask character type. In this case, the return value is always set to True.

True when the character is valid for the mask character type. Position in the control value and mask examined in the method. Character value examined in the method. Indicates if the character originates from a Paste operation (Ctrl+V or Shift+Insert). Clears values in the current selection for the control.

DeleteSelected is a method used to clear values in the current selection for the control. DeleteSelected calls GetSel to determine the starting and ending positions for characters currently selected in the control. DeleteSelected calls SetCodePoint to store blank values for mask positions selected in the value for the control.

DeleteSelected calls RealSetTextWhileMasked to store the updated Text value in the control. SetCursorPos is called to update the caret position in the control.

No actions are performed in the method when HasSelection returns False. Deletes one or more characters at the current cursor position.

The number of characters affected in the method is determined by the value from HasSelection. When True, the current selection is control is affected. When False, a single character value is deleted.

When True the following character(s) are deleted; when False the preceding character(s) are deleted. Registers the widget set class reference used to create new instances of the control. Applies the edit mask in the control to the specified value.

ApplyMaskToText is a TCaption function used to apply the edit mask in the control to the text specified in Value. This method mimics the behavior implemented in Delphi version 3, including:

Pads the text with blank values if needed when literals are not used in the mask.
When literals are present in the edit mask, matching literals in the text are located and processed as "segments" with the literal(s) used as delimiters.

Some examples to clarify:

	EditMask	Text to be set	Result
99	1	1_
cc-cc	1-2	1_-2_
!99	1	_1
!cc-cc	1-2	_1-_2
cc-cc@cc	1-2@3	1_-2_@3_
cc-cc@cc	12@3	12-__@3_
cc-cc@cc	123-456@789	12-45@78
!cc-cc@cc	123-456@789	23-56@89

This feature seems to have been invented for use with dates:

	EditMask	Text to be set	Result
99/99/00	23/1/2009	23/1_/20 if your locale DateSeparator is '/'
!99/99/00	23/1/2009	23/_1/09 if your locale DateSeparator is '/'

The resulting text will always have the length defined for the TInternalMask type used in the control. The new text value does not have to pass validation.

ApplyMaskToText is called from the SetTextApplyMask when IsMasked contains True (EditMask has a non-zero length).

Value after mask literals and space substitution is applied. Value examined and updated in the method. Indicates if the control can display its Hint or TextHint using the LCL capability layer.

CanShowEmulatedTextHint is an overridden Boolean function which indicates if the control can display its Hint or TextHint using the LCL capability layer in the Widget set class. CanShowEmulatedTextHint returns False when an edit mask has been assigned for the control. Otherwise, the inherited method is called to get the return value for the method.

TCustomEdit.CanShowEmulatedTextHint False if a value has been assigned to EditMask. Saves and disables the edit mask in the control.

DisableMask is a Boolean function used to save the current edit mask to an internal member, and then disables the edit mask in the control. This gives developers the opportunity to set any text in the control without affecting the control state. Whether or not the function succeeds, NewText will be set as the new Text in the control. There is no need to retain the saved internal mask or trim type; they are only set in SetEditMask.

Use RestoreMask to re-enable the saved edit mask for the control.

Returns True on success, or False when an edit mask is not used in the control. New value for the Text property in the control. Performs actions when the control value is invalid for its edit mask.

Signals the OnValidationError event handler (when assigned). It is called from the ValidateEdit method when TextIsValid returns False and ValidationErrorMode is set to mvemEvent.

Restores the saved edit mask in the control.

RestoreMask is a procedure used to restore the saved edit mask in the control. The edit mask is saved when DisableMask is called and an edit mask is active for the control. The return value is True when the edit mask (and control state and value) are successfully restored.

In either circumstance, the value in NewText is assigned as the value for the Text property in the control.

True on success. New value assigned to the Text property. Sets the value for the Text in the control.

RealSetText is an overridden procedure used to set the value for the Text in the control.

Setting the value in Text prior to completion of LCL component streaming has unwanted side-effects. To prevent the condition, RealSetText stores the text in AValue to an internal member that is applied in the Loaded method. No additional actions are performed in the method when csLoading is in the ComponentState property.

RealSetText uses the value from IsMasked to determine if an edit mask is used for the control. When False, the inherited RealSetText method is called to set the value in the Text property. When True, the SetTextApplyMask method is called to store the content in AValue guided by the EditMask for the control.

Value stored in the text for the control. Gets the value for the Text in the control.

RealGetText is an overridden TCaption function used to get the text value for the masked edit control. It calls the inherited method on entry to get the caption text for control. The value may contain mask literals inserted when the EditMask was applied to the value. When IsMasked is True, the GetTextWithoutMask method is called to remove the mask literals.

TCustomEdit.RealGetText Text for the control without mask literals. Gets the text value for the control without formatting applied by an edit mask.

GetTextWithoutMask is method used to get the text for the specified Value without the formatting applied by the EditMask. It ensures that any occurrences of SpaceChar not used as a mask literal are replaced with #32. Other mask literals are removed from Value. If the mask indicates it is saved as part of the data, leading or trailing whitespace is trimmed as required.

GetTextWithoutMask is used in the implementation of the RealGetText method.

Value for the control without formatting applied by EditMask. Text value for the control without mask characters or formatting. Gets the value for the control without the Space character literal used in the edit mask.

GetTextWithoutSpaceChar is similar to GetTextWithoutMask - but leaves mask literals other than SpaceChar intact. It replaces all occurrences of SpaceChar that are not used as a mask literal with #32.

GetTextWithoutSpaceChar is used in the implementation of the Delphi compatible FormatMaskText routine.

Text value for the control after the SpaceChar literal is converted to its conventional representation (#32). Masked caption value examined and converted in the method. Sets the value for the control after applying its edit mask.

SetTextApplyMask is a method used to set the text for the control to the specified Value. It ensures that the EditMask is applied to the value when IsMasked returns True. The ApplyMaskToText method is called to generate the text with mask literals as needed for the EditMask.

RealSetTextWhileMasked is called to apply the masked text value to the control.

When Value is an empty string (''), the Clear method is called to set the control value.

SetTextApplyMask is used in the implementation of the RealSetText method. It is also called from the Loaded method when the component has finished loading during LCL streaming.

Text before mask literals in EditMask are applied. Gets the value for the EditText property.

GetEditText is a String function used to get the value for the EditText property. It contains the text displayed in the edit box for the control including any mask literals and formatting required for the EditMask. The value is retrieved by calling the overridden RealGetText method for the control.

Value for the EditText property. Sets the value for the EditText property.

SetEditText sets the value for the Text displayed in the control. The new value for the text is padded (when needed) to the length defined in the edit mask. SetEditText calls RealSetTextWhileMasked to store the value in the Text in the control.

This method is not Delphi compatible, but this is by design. Delphi allows setting the EditText to any length, which is extremely dangerous! This method ensures that the text assigned in the control does not exceed the length specified by its edit mask. New value for the EditText property. Finds the starting and ending positions for the selection. GetSel finds the starting and ending positions for the selected text in the control. Calls GetSelStart to get the value for the _SelStart argument. Calls GetSelLength to get the number of characters selected, and calculates the value for _SelStop. Stating position for the text selected in the control. Ending position for the text selected in the control. Specifies the starting and ending positions for the text selected in the control. SetSel specifies the starting and ending positions for the text selected in the control. Starting position for text selected in the control. Ending position for text selected in the control. Performs actions when the value in the Text property has been changed.

TextChanged is an overridden procedure used to respond to a change in the value for the Text property. Its purpose is to avoid leaving the control in an invalid state when:

A Cut, Paste, or Clear operation from an Operating System context menu. We try to catch and handle these messages.
Dragging selected text in the control with the mouse.

If one of these operations happen, then the internal logic for cursor positioning and character insertion can be invalid. So, we simply restore the text value from an internal member used to track the current text value.

The inherited TextChanged method is called when IsMasked is False, or when an internal update to the control value is performed. Otherwise, RealSetTextWhileMasked is called followed by SetCursorPos.

TCustomEdit.TextChanged Suppresses the OnChange event when the initial value for the control is assigned.

Change is an overridden procedure used to perform actions when the value for the control is changed. Change suppresses firing the OnChange event handler when the initial value for the control is assigned by using an internal member variable in the class instance. If the variable is not set, the inherited Change method is called to signal the OnChange event handler (and/or the OnChangeHandler event handler) for the control.

TCustomEdit.Change TCustomEdit.OnChange Sets the value in the CharCase property.

SetCharCase is an overridden procedure used to set the value in the CharCase property.

SetCharCase is modified in TCustomMaskEdit to ensure that the correct value is used when an edit mask has been assigned in the control. CharCase is set to the value ecNormal when IsMasked contains True. It is assumed that case conversions are performed according to the rules for the edit mask.

When IsMasked is False, the property is set to the content in the Value argument.

SetCharCase calls the inherited method to store the new value for the property.

TCustomEdit.CharCase New value for the property. Sets the value for the MaxLength property. New value for the property. Gets the value for the MaxLength property. Value for the property. Sets the value for the NumbersOnly property.

SetNumbersOnly is an overridden Boolean function used as the write access specifier for the NumbersOnly property.

SetNumbersOnly provides support use of an edit mask in the control. When IsMasked is True, setting NumbersOnly to True can interfere with the masking logic in the control; the property is automatically set to False when IsMasked is True. Otherwise, the inherited SetNumbersOnly method is called to set to the value for the property.

TCustomEdit.SetNumbersOnly TCustomEdit.NumbersOnly New value for the property. Performs actions when a component has been loaded from the LCL streaming mechanism.

Loaded is an overridden procedure used to perform actions when a component has been completely loaded from the LCL component streaming mechanism. Loaded calls the inherited method, and sets the value in internal members used to track the EditMask and Text values in the control.

TWinControl.Loaded LMPasteFromClip is the LCL message method for pasting from the clipboard. LMCutToClip is the LCL message method for cutting to the clipboard. LMClearSel is the LCL message method for clearing selected items. If True, the Edit box is allowed to modify its contents.

EditCanModify always returns True in TCustomMaskEdit. It is a virtual method, and can be overridden in descendent classes (like TDBEdit).

True if the control can modify its text value. Reset returns the edit to its default state with mask appearing in Text box and no string input. Performs actions needed when the control is entered.

DoEnter is an overridden procedure used to perform actions needed the control is entered. DoEnter extends the behavior in the inherited method to track the value for control when entered and to perform auto selection logic when an edit mask is in use.

TCustomEdit.DoEnter Performs actions needed when the control is exited. TCustomEdit.DoExit Performs actions needed to apply key down messages.

Calls the inherited KeyDown method. If an edit mask is not assigned in the control, no additional actions are required in the method.

KeyDown handles the following keys, and performs the following actions:

Shift + Left, Shift + Right, Shift + Home, Shift + End: Ignored
Escape: Resets text to the un-edited value
Shift + Delete: Cuts selection to the clipboard
Ctrl + Delete: Deletes the current selection
Delete: Deletes the character at the cursor position
Ctrl + Backspace: Deletes the current selection
Shift + Backspace: Cuts the current selection to the clipboard
Backspace: Deletes the character prior to cursor position
Shift + Insert: Paste from the clipboard
Ctrl + Insert: Copy to the clipboard
Ctrl + C: Copy to the clipboard
Ctrl + X: Cut to the clipboard
Ctrl + V: Paste from the clipboard
Ctrl + Left, Left: Select the previous character
Ctrl + Right, Right: Selects the next character
Home: Move to the first character in the control
End: Move to the end of the control
Up, Down: Ignored
Ctrl + A: Selects all of the text in the control

TWinControl.KeyDown Key code examined in the method. Key modifier examined in the method. Handle all keys from KeyPress and Utf8KeyPress.

HandleKeyPress is a method used to handle keys forwarded from the KeyPress and UTF8KeyPress methods. No actions are performed in the method if the control is ReadOnly, or IsMasked returns False.

HandleKeyPress set the cursor position to the start of the current selection in the control. If the cursor is on a mask literal, it is advanced to the next writable position.

When Key is a Period ('.') or a Comma (',') character, the cursor is advanced to the next Period or Comma character in the mask. For other character values, the InsertChar method is called.

The value in Key is set to an empty string ('') when it is handled in the method.

Character value for the key examined in the method. Performs actions needed to handle the specified character in the control.

KeyPress is an overridden procedure used to apply the character specified in Key to the control. KeyPress calls the inherited method, and converts the character in Key to a UTF-8-encoded character which is passed to the HandleKeyPress method. All character values handled in HandleKeyPress are set to an empty character, and causes the value in Key to be digested in the method.

TWinControl.KeyPress Character handled in the method. Handles a key press with the specified UTF-8 character value.

Utf8KeyPress is an overridden method in TCustomMaskEdit, and calls the inherited method on entry to signal the OnUTF8KeyPress event handler (when assigned).

UTF8Key contains the UTF-8-encoded character for the key press notification. The value in UTF8Key may be set to an empty character ('') if it has been handled in the ancestor method.

Utf8KeyPress calls the HandleKeyPress method to apply the character value to the control. It is only called when UTF8Key contains a multi-byte UTF-8 character value. Otherwise, the key event is handled by the KeyPress method.

TWinControl.UTF8KeyPress TWinControl.OnUTF8KeyPress UTF-8-encode key handled in the method. Performs actions needed to handle a mouse button up message.

Calls the inherited MouseUp method. When a mask is used in the control, the cursor is moved to the beginning of the current selection in the control and SetCursorPos is called to update the caret position.

TCustomEdit.MouseUp Mouse button for the message. Shift modifier for the message. Horizontal coordinate for the mouse position. Vertical coordinate for the mouse position. Updates the position for the cursor (or caret) when an EditMask is used in the control.

CheckCursor is a procedure used to update the position for the cursor (or caret) when an EditMask is used in the control. CheckCursor uses the value from IsMasked to determine if the cursor position needs to be updated by calling SetCursorPos. When IsMasked returns False, no actions are performed in the method.

Used in the implementation of the SetSpaceChar method.

Value entered in the control and obscured / formatted using the EditMask.

Calls the inherited RealGetText method to get the value for the property. When a new value for the property is assigned, mask literals are restored for the new value to ensure that the control is in a recoverable state. EditText is truncated, or padded with ClearChar as needed, so that the value matches the length for the EditMask. These actions are not performed when IsMasked returns False (EditMask has not been assigned).

SetEditText is not Delphi compatible. Delphi allows any text value to be assigned to the control, leaving the control in an unrecoverable state where it is impossible to leave the control because the text can never be validated. The LCL implementation does not allow this. True if a non-empty value has been assigned to EditMask. Contains the value used to represent Space (#32) characters in the control value.

SpaceChar is a Char property with the value used to represent Space (text) characters in the value for the control. It corresponds to the '_' character used the mask fields.

When a Space character is found in the text for the control, or a value has not been provided for a masked character position, it is replaced with this character.

The default value for the property is '_'.

Setting a new value for the property causes the existing text in the control to be updated. All occurrences of the existing SpaceChar are converted to the new value for the property, and stored as the new text for the control. The cursor position and text selection are updated when the text is stored.

SpaceChar is not used when EditMask is an empty string (''), or IsMasked is False.

Indicates the maximum number of characters that can be stored in the value for the control.

MaxLength is an Integer property that represents the maximum number of characters that can be stored in the edit control. TCustomMaskEdit re-implements the read and write access specifiers for the property to provide support for use of an edit mask in the control.

Setting a new value for the property causes the internal length for the edit mask to be used as the value property. The specified Value is discarded when IsMasked is True. Otherwise, the new Value is stored using the inherited property accessor.

TCustomEdit.MaxLength Contains the mask characters classes and literals used to format/obscure the value for the control.

EditMask is a String property which contains the mask specification for the edit control. EditMask contains the delimited mask fields with the character types, storage specifier, and the character value used to represent a space in the edit mask. For example:

AMaskEdit.EditMask := '999.999;1;0';

The EditMask is formed using a pattern of characters with the following meaning:

\	after this you can set an arbitrary char
>	after this the characters are in in uppercase
<	after this the character are in lowercase
l	only an optional letter
L	only a letter
a	an optional alphanumeric character (['A'..'Z','a..'z','0'..'9'])
A	an alphanumeric character
c	any optional Utf-8 character (including a Space character)
C	any Utf-8 character in the range #33-#255 (does not include Space)
9	only an optional number
0	only a number
#	only an optional number or + or -
:	displays the hour separator character
/	displays the date separator character
h	an optional hexadecimal character (Lazarus extension, not supported by Delphi)
H	a hexadecimal character (Lazarus extension, not supported by Delphi)
b	an optional binary character (Lazarus extension, not supported by Delphi)
B	a binary character (Lazarus extension, not supported by Delphi)
!	Trim leading or trailing blanks, depending on position of the mask character

Setting a new value for the property causes the value to be decomposed into the internal TInternalMask representing the individual characters in the edit mask. Individual UTF-8 characters in Value are either added to the mask as literals or character types. Clear is called to remove the displayed value in the control, and the initial Text value is set to the value from RealGetText.

Indicates the action taken when the control value is invalid for its mask.

ValidationErrorMode is a TMaskEditValidationErrorMode property which indicates the action taken when the value for the control is invalid for the mask in the EditMask property.

The default value for the property is mvemException, and causes an exception to be raised when control value is invalid for its mask. Use mvemException to cause the OnValidationError event handler to be signalled for the validation error.

The property value is used in the ValidateEdit method when IsMasked is set to True and the EditText for the control is not valid.

Constructor for the class instance.

Create is the overridden constructor for the class instance. Create sets the default values for internal members and properties specific to TCustomMaskEdit. The value in SpaceChar is set to '_'.

Create calls the inherited constructor, and sets the value in the internal member used for the text in the edit control by calling the inherited RealGetText method.

TCustomEdit.RealGetText Owner for the class instance. Clears the value for the edit control.

Clear is an overridden procedure used to clear the value for the text in the edit control. Clear uses the value from IsMasked to determine if a mask specification has been assigned for the edit control.

When IsMasked is True, the ClearChar method is called for each position in the EditMask to get the blank value for the mask character. RealSetTextWhileMasked is called to store the new value for the control. The cursor (or caret) is reset to the beginning of the text, and SetCursorPos is called to update the cursor position.

When IsMasked is False, the inherited Clear method is called to update the content for the control.

Clear is used in the implementation of the SetEditMask, RestoreMask, and SetTextApplyMask methods.

TCustomEdit.Clear Selects all of the text in the masked edit control.

SelectAll is an overridden method used to select all of the text in the masked edit control. SelectAll ensures that content formatted using the EditMask is handled in the method.

When IsMasked is True, the inherited RealGetText method is called to get the text content for the control. SelStart and SelLength are updated to use the values needed for the text content. The inherited method is not called.

When IsMasked is False, the inherited method is called to handle the text selection.

TCustomEdit.RealGetText TCustomEdit.SelectAll TCustomEdit.SelStart TCustomEdit.SelLength Validates the value for the edit control when an EditMask has been specified.

ValidateEdit is a procedure used to validate the text for the edit control using the assigned mask. ValidateEdit uses the value in IsMasked to determine if a mask has been assigned in the control.

When IsMasked is True, the value for the control is validated. The TextIsValid method is called with the value from the Text property. If the Text is not valid, an EDBEditError exception is raised for the error condition.

When IsMasked is False, no actions are performed in the method.

ValidateEdit is used in the implementation of the DoExit method.

Raises an EDBEditError if the Text for the control is not valid. Raised with the message in SMaskEditNoMatch. Enables or disables use of set notation in the EditMask.

EnableSets is an experimental Boolean property. It is used when a new value assigned to the EditMask property is parsed to reconstruct the internal mask characters and literals for the control.

When set to False, the '[' and ']' characters used in set notation are treated as literal characters. When set to True, the optional or required set definition is added to the mask. The default value for the property is False.

Indicates if the value for the edit control has been changed.

Modified is a Boolean property which indicates if the value for the edit control has been changed.

Event handler signalled when the value for the masked edit control is invalid.

OnValidationError is a TNotifyEvent property with the event handler signalled when the value for the masked edit control is invalid for its EditMask.

TMaskEdit is an Edit box with characters masked out to avoid unauthorized reading.

TMaskEdit is used to display an Edit Box with the input text masked by a selected character specified by PasswordChar, usually an asterisk, or by EditMask (a complete string), specified in TCustomMaskEdit.

Useful for inputting passwords or capturing input using a specific format and validation.

Determines the case for the text in the masked edit control.

Indicates how text is displayed in a text editing control in the following ways:

Normal case letters
Upper case letters
Lower case letters

The rules can, of course, be overridden by use of the shift key.

TCustomEdit.CharCase" A context-sensitive menu that pops up when the right mouse button is clicked over this control.

One of the standard properties, which should be supported by all descendants.

Reads the details of the pop-up menu, or stores them. Properties are defined in the parent class TPopupMenu.

Flag to determine if the hint is displayed for this control.

One of the standard properties, which should be supported by all descendants.

Reads flag or writes one to determine if a hint is to be shown when mouse hovers over this control. If value is stored, a storage flag is set. Display of the actual hint is controlled by OnShowHint.

Keyboard navigation order for the control when Tab is pressed.

Keyboard navigation order for the control in it Parent control when the Tab key is pressed. The default value for the property is -1.

Use TabStop to enable or disable keyboard navigation for the control.

TWinControl.TabOrder Enables or disables keyboard navigation using the Tab key.

Use the TabStop property to allow or disallow access to the control using the Tab key. If TabStop is True, the control is in the tab order. If TabStop is False, the control is not in the tab order and the user can't use the Tab key to move to the control.

TCustomEdit.TabStop TWinControl.TabStop Indicates if the control is visible or hidden.

The Visible property indicates the ability to see a visual control. If Visible is True the control is shown, otherwise it is hidden. Calling Show sets Visible to True. Setting Visible to False is equivalent to calling the Hide method.

The Visible property does not reflect the visibility for a parent control. Use the IsVisible method to consider this and get the effective visibility. TControl.Visible Handles a key down event for the focused control.

OnKeyDown is an event handler signalled when a key is down while control has focus.

Differs from OnKeyPress in that the key may have already been down when the control received focus; with OnKeyPress the key needs to become pressed while the control has focus.

TWinControl.OnKeyDown Handles a key press event for the focused control.

OnKeyPress is an event handler signalled when a key is pressed while the control has focus.

Differs from OnKeyDown in that the key needs to become pressed while the control has focus; with OnKeyDown the key may have already been down when the control received focus.

TWinControl.OnKeyPress Handles a key up event for the focused control.

OnKeyUp is an event handler signalled when a key is released (not pressed) while the control has focus.

The key may already have been up when the control received focus, or a pressed key may become released during the time the control has focus.

TWinControl.OnKeyUp Contains the value for the control.

Text is a public String property in TMaskEdit which provides access to the value for the edit control.

TCustomEdit.Text TControl.Text Applies an edit mask to the specified string value.

FormatMaskText is a String function used to apply an edit mask to the specified String value. FormatMaskText creates a temporary instance of TCustomMaskEdit that is used to apply the edit mask in AEditMask when required. The value in AEditMask is assigned to the EditMask property in TCustomMaskEdit.

The Value argument contains the data without any mask literals, escaped characters, or space characters inserted by the editing mask. When the IsMasked method in the TCustomMaskEdit returns True, the ApplyMaskToText method is used to generate the return value for the routine. To maintain Delphi compatibility, the GetTextWithoutSpaceChar is also called to translate space characters represented using the character in the mask field to the Space character (decimal 32).

When IsMasked is False, the unmodified content in Value is used as the return value.

Value after applying the specified mask. Edit mask applied to the specified content. Original content modified in the routine. Separates fields in the edit mask into the arguments passed to the routine.

SplitEditMask is a procedure used to separate fields in the edit mask into arguments passed to the routine. AEditMask is the editing mask with the delimited fields to examine the procedure. If AEditMask contains a value like:

'999.999;0;_'

The procedure returns the following values in the corresponding arguments:

AMaskPart - Mask characters: '999.999'.
AMaskSave - Indicates if mask characters are included in the value for a control: False. Optional. Default value is True.
ASpaceChar - Character used to represent a space in the masked value: '_'. Optional. Default value is DefaultBlank. Not relevant when AMaskSave is False.

SplitEditMask is used in the implementation of the SetEditMask method in TCustomMaskEdit.

Delimited mask specification examined in the method. Contains the mask characters or literals in the specification. Indicates if mask data is saved with the value in a control. Character representing the Space character in the masked value. Registers component for use in the Lazarus IDE.

Register is a procedure used to register components in the maskedit.pp unit for use in the Lazarus IDE. Register calls RegisterComponents to add the TMaskEdit class to the Additional tab in the Lazarus IDE.

RegisterComponents