Defines classes for a masked edit control, i.e. editing with a masking string in place to obscure, format, or validate the text entered in the control

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

Additional Tab

TMaskEdit

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. 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 used in the implementation of TCustomMaskEdit.

Lazarus extension, not supported by Delphi. Lazarus extension, not supported by Delphi. Lazarus extension, not supported by Delphi. Lazarus extension, not supported by Delphi. Lazarus extension, not supported by Delphi. Lazarus extension, not supported by Delphi. Lazarus extension, not supported by Delphi. Lazarus extension, not supported by Delphi. Array type used to represent an edit mask in TCustomMaskEdit

TInternalMask is an array type which contains up to 255 UTF-8-encoded character values. It is used to implement internal members in TCustomMaskEdit, and exposed as 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 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.

There is no good reason for the name used for this exception. It has nothing to do with databases. Ancestor for UTF-8 exceptions

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

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

EInvalidCodePoint is an EInvalidUtf8 descendant that implements the Exeption 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 Ancestor 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. So please note:

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 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 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 used in DoEnter 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 UTF-8 character to the internal mask value

AddToMask is a procedure used to append the UTF-8 character in Value to the internal mask for the edit control. AddToMask increments the internal counter which tracks the length of the mask value, and stores Value at the end of the TInternalMask instance.

Used in the implementation of the SetMask procedure which sets the value for the EditMask property.

UTF-8 character appended to the mask for the edit control Sets the value for the Modified property Value for the property Sets the value for the EditMask property New value for the EditMask property 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.

Please note: 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.

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 occurrance of the specified character in the value for the edit control

JumpToNextDot is a procedure used to move to the next occurrance 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 occurrance of Dot, and the next occurrance cannot be the last character in the mask.

JumpToNextDot calls the SetCursorPos method to update the caret position in the edit control.

JumpToNextDot is used in the implementation of the HandleKeyPress method.

Character 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 Transforms the specified UTF-8 character to a TMaskType enumeration value

CharToMask is a TMaskedType function used to transform the UTF-8-encoded character in UCh to a value from the TMaskedType enumeration. UCh cannot contain a multi-byte UTF-8 value; it must be a single byte value. No actions are performed in the method when UCh contains multiple byte values in the UTF-8 code point. The ordinal value for the character is used to get the corresponding TMaskedType enumeration value used as the return value for the method.

CharToMask is used in the implementation of the following methods:

IsMaskChar
SetSpaceChar
IsLiteral
CharMatchesMask
ClearChar
CanInsertChar

TMaskType value for the specified character UTF-8 character examined in the method Transforms the specified TMaskType enumeration value into a character for use in TInternalMask

MaskToChar is a Char function used to transform the specified TMaskType enumeration value into a character for use in the internal TInternalMask instance in the control. The return value from MaskToChar is passed as an argument to the AddToMask method to populate the TInternalMask for the control.

MaskToChar is used (along with AddToMask) in the implementation of the SetMask method (the write access specifier for the EditMask property).

Character value to add to the internal mask structure for the control TMaskType enumeration value converted in the method Indicates whether the specified character is a valid mask character

IsMaskChar is a Boolean function used to determine if the UTF-8 character in Ch is a valid mask character. Ch contains one the characters values from the TInternalMask used in the control. IsMaskChar returns True when the value in Ch is any of the TMaskType values other than Char_Start.

IsMaskChar is used in the implementation of methods like IsLiteral and SetSpaceChar.

True when the character is a mask type character other than Char_Start Mask type character examined in the method Indicates whether the specified character is a mask literal

IsLiteral is a Boolean function which indicates whether the UTF-8 character in Ch represents a mask literal which cannot be edited in the control. The return value is False for any of the following conditions:

IsMaskChar(Ch) returns False
IsMaskChar(Ch) does not return Char_HourSeparator or Char_DateSeparator

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

Indicates whether the specified valuel 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. When Position is not in this range, no actions are performed in the method and the return value is set to False.

CharMatchesMask calls CharToMask to convert the mask character at Position to a TMaskType enumeration value which determines if the value in Ch is valid. The return value is True when Ch contains a valid character value for the mask character type.

CharMatchesMask is used in the implementation of the TextIsValid method.

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

Fixed literals, like date or time separators, and escaped characters are ignored in the method. For Delphi compatibilty, only literals remain; all other character values are replaced with the character designated in the SpaceChar property.

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 in Ch 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 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.

Please note: 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 preceeding 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 feauture seems to be invented for easy use of 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 length defined for the TInternalMask type used in the control. The new text value does not have to pass validation.

Indicates if the control can display its Hint or TextHint using the LCL capatibility layer

CanShowEmulatedTextHint is an overridden Boolean function which indicates if the control can display its Hint or TextHint using the LCL capatibility 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 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 SetMask.

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 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 successfullly restored.

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

True on success New vaule 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 Gets the raw value for the control without formatting applied by an edit mask Gets the value for the control without Space characters inserted by an edit mask Sets the value for the control after applying its edit mask Gets the text in the edit box (the string value that has been masked) Sets the value for the Text displayed in the control

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.

Please note: This method is not Delphi compatible, but it 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 applied to the Text in the control 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

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, Paster, 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 the contents 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. If Key and Shift are extended selection navigation keys, no additional actions are required; i. e. Shift+Left, Shift+Right, Shift+Home, Shift+End.

KeyDown ensures that the value in the control is reset to its value on entry when Key is the Escape key. KeyDown provides support for clipboard operations, as well as the Delete and Backspace keys.

KeyDown handles Ctrl navigations keys as if they were the unmodified variant of the key; i. e. Ctrl+Left, Ctrl+Right, Ctrl+Home, Ctrl+End. Please note that the Ctrl+Up and Ctrl+Down key and modifier are not valid in TCustomMaskEdit; the keystroke is digested.

TWinControl.KeyDown Key code examined in the method Key modifier 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 Perfoems 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.

The string that has been typed in the Edit Box and obscured by the Masking characters isMasked is True if the text is masked SpaceChar is the character that is to be used as a Space character 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 EditMask - the sequence of characters used to obscure the string being typed (typically a sequence of asterisks)

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 used to represent a space in the edit mask. For example:

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

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

\	after this you can set an arbitrary char
>	after this the chars is in upper case
<	after this the chars is in lower case
l	only a letter but not necessary
L	only a letter
a	an alphanumeric char (['A'..'Z','a..'z','0'..'9']) but not necessary
A	an alphanumeric char
c	any Utf8 char but not necessary
C	any Utf8 char #32 - #255
9	only a number but not necessary
0	only a number
#	only a number or + or -, but not necessary
:	automatically put the hour separator char
/	automatically put the date separator char
h	a hexadecimal character but not necessary (Lazarus extension, not supported by Delphi)
H	a hexadecimal character (Lazarus extension, not supported by Delphi)
b	a binary character but not necessary (Lazarus extension, not supported by Delphi)
B	a binary character (Lazarus extension, not supported by Delphi)
!	Trim leading blanks, otherwise trim trailing blanks from the data

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.

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 SetMask, RestoreMask, and SetTextApplyMask methods.

TCustomEdit.Clear 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. 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. Discuss relationship between Text, EditText, RealSetText, et. al. 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.

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

Determines how the control is to be anchored to its client or parent control.

Either reads a flag containing the set of anchors to be used, or writes a set of anchors. If they have been written, this is indicated in IsAnchorsStored.

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

AutoSize permits the size of a control to be adjusted automatically, for example a button can become bigger or smaller to accommodate a longer or shorter caption.

Reads logical (boolean) flag to see whether auto-sizing is to be operated, or writes the flag to say it should be done. Default is false, i.e. no auto-sizing.

Determines the border spacing for this control

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

Determines the border spacing for this control.

Reads flag to find stored spacing values required for the border of the control, or writes the flag to set the spacing.

The properties are defined in the parent class TControlBorderSpacing.

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.

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

Reads the value for color, or stores the value, and sets a flag if the color is stored.

The default color is the same as the window in which the control is located.

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

Determine Constraints (max and min height and width) for this control; reads the size constraints or stores new ones.

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

Whether the control is Enabled. If not, it usually appears 'greyed-out'.

Reads a flag to see whether the control is enabled, or stores a new value. If stored, sets a flag to say so.

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

Reads a flag to see what font should be used, or sets a flag to store it. If stored, sets a flag to say so.

The properties of Font are defined in the parent class TFont.

PopupMenu - 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.

ReadOnly indicates if the contents of the edit box may only be read, not written or erased 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.

Reads or writes information in flag; default is -1.

Reads or writes boolean flag; default is False.

Use the TabStop 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.

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, among others, Visible to True. Setting Visible to False is equivalent to calling the Hide method.

The Visible property does not depend on the visibility for a parent control. Use the IsVisible method to consider this and get effective visibility.

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

This is often the default action for many controls, and is often the ONLY action specified by the programmer. The action can be specified by the user, either by typing explicit code into the implementation section for this control, or by selecting an action from a pre-supplied ActionList.

Reads or writes a flag if a mouse click is detected, and sets a flag if a value is stored.

Double-clicking is much more common in a Windows environment than in Unix or Linux, where single-clicking is the default method for selecting an object. However, in all environments there could be valid use for a double-click, and a method should be supplied if appropriate.

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.

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.

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 Text is a public property in TMaskEdit which provides access to the value for the edit control. TCustomEdit.Text TControl.Text Discuss relationship between Text, EditText, RealSetText, et. al. 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 SetMask method in TCustomMaskEdit.

Delimited mask specification examined in the method Contains the mask chatracters 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