Class MaskedEditBox

The MaskedEditBox control provides restricted data input as well as formatted data output. This control supplies visual cues about the type of data being entered or displayed.

Inheritance
System.Object
TextBoxExt
MaskedEditBox
GridMaskedEditBox
MaskedEditBoxExt
Implements
System.ComponentModel.ISupportInitialize
System.Runtime.Serialization.ISerializable
Inherited Members
Namespace: Syncfusion.Windows.Forms.Tools
Assembly: Syncfusion.Shared.Base.dll
Syntax
public class MaskedEditBox : TextBoxExt, IThemeProvider, ISupportInitialize, IVisualStyle, ISerializable
Remarks

The MaskedEditBox is derived from System.Windows.Forms.TextBox and is fully compatible with the textbox control.

The MaskedEditBox control generally behaves as a textbox control with enhancements for optional masked input and formatted output. If you do not use an input mask, the MaskedEditBox control behaves much like a textbox.

If you define an input mask using the Mask property, each character position in the MaskedEditBox control maps to either a placeholder of a specified type or a literal character. Literal characters, or literals, can give visual cues about the type of data being used. For example, the parentheses surrounding the area code of a telephone number are literals: (919).

If you attempt to enter a character that conflicts with the input mask, the control generates a ValidationError event. The input mask prevents you from entering invalid characters into the control.

The MaskedEditBox control provides full support for the Windows Forms designer and you can just drag-and-drop the control and set the properties.

The MaskedEditBox control provides full support for data binding. The ClipMode property has to be set to ExcludeLiterals when the MaskedEditBox's Text property is bound to a DataColumn that only accepts numerical data.

The DataGroups property provides the ability to break down the MaskedEditBox's content into different data groups. The data groups can be defined through the designer and is defined by the length of the data group. For example, a mask of type (###) ### - #### Ext 9999 representing a telephone number can be broken down into 3 data groups with the names "AreaCode", "PhoneNumber" and "Extension" by setting the group lengths to be 5, 11, 9. You can access the DataGroups and the values they hold through an index based accessor or name based accessor.

Examples
            // InitializeComponent
            // Create the Masked edit box control:
            this.maskedEditBox1 = new MaskedEditBox();

            // Specifies if the prompt character can be entered:
            this.maskedEditBox1.AllowPrompt = false;

            // The mask string:
            this.maskedEditBox1.Mask = ">?<????????????";

            // The max length is set based on the mask:
            this.maskedEditBox1.MaxLength = 13;

            // The clip mode specifies if the literals are included:
            this.maskedEditBox1.ClipMode = ClipModes.IncludeLiterals;

            // The date time format:
            this.maskedEditBox1.TimeSeparator = ':';
            this.maskedEditBox1.DateSeparator = '-';

            // The number format:
            this.maskedEditBox1.DecimalSeparator = '.';
            this.maskedEditBox1.ThousandSeparator = ',';

            // Add the MaskedEditBox control to the form:
            this.Controls.Add(this.maskedEditBox1);

Constructors

MaskedEditBox()

Creates an object of type MaskedEditBox and initializes it.

Declaration
public MaskedEditBox()
Remarks

The default Mask is initialized to an empty string and this will result in the MaskedEditBox acting the same as a text box initially.

MaskedEditBox(SerializationInfo, StreamingContext)

Declaration
protected MaskedEditBox(SerializationInfo info, StreamingContext context)
Parameters
Type Name Description
System.Runtime.Serialization.SerializationInfo info
System.Runtime.Serialization.StreamingContext context

Properties

AllowPrompt

Indicates whether the prompt character can be allowed to be entered as an input character.

Declaration
public bool AllowPrompt { get; set; }
Property Value
Type Description
System.Boolean
Remarks

Set the value to True if the prompt character can be entered by user.

BackColor

Declaration
public Color BackColor { get; set; }
Property Value
Type Description
System.Drawing.Color

CanUndo

Indicates whether the Undo operation is possible at this time.

Declaration
public bool CanUndo { get; }
Property Value
Type Description
System.Boolean
Remarks

The MaskedEditBox maintains its own undo mechanism and hence needs to implement this method to be compatible with the Undo mechanism.

ClipMode

Gets / sets the format of the text that will be returned by the MaskedEditBox control. The nature of the formatting is set through the ClipModes type.

Declaration
public ClipModes ClipMode { get; set; }
Property Value
Type Description
ClipModes
Remarks

See the ClipModes type for the possible values and more information.

ClipText

Returns the text in the MaskedEditBox control, excluding literal characters of the input mask.

Declaration
public string ClipText { get; }
Property Value
Type Description
System.String
Remarks

For example if the content of the MaskedEditBox is 99-222-9999, the mask is ##-###-###, the ClipText will return 992229999.

Culture

Gets / sets the culture that is to be used for formatting the currency display.

Declaration
public CultureInfo Culture { get; set; }
Property Value
Type Description
System.Globalization.CultureInfo

DataGroups

The MaskedEditBox can be defined to hold multiple data groups.

Declaration
public MaskedEditDataGroupInfoCollection DataGroups { get; }
Property Value
Type Description
MaskedEditDataGroupInfoCollection
Remarks

The DataGroups can be added through the designer. DataGroups are defined by the length of the group. The value of the group can be accessed by the index of the group or through the name of the group.

A MaskedEditBox with a mask (###) ###-#### Ext 9999 representing a US phone number and extension can be defined to have 3 groups - representing the AreaCode, PhoneNumber, and Extension. The groups would have lengths of 5, 11 and 9 in that order.

The DataGroup's value is affected by the ClipMode property.

DateSeparator

Gets / sets the character to use when a date separator position is specified.

Declaration
public char DateSeparator { get; set; }
Property Value
Type Description
System.Char
Remarks

This value is initially set from the System.Globalization.DateTimeFormatInfo and can be changed based on your requirements or based on the locale.

DateTimeFormatInfoObject

Gets / sets the System.Globalization.DateTimeFormatInfo provides the necessary globalization information for the properties that rely on the datetime settings.

Declaration
public DateTimeFormatInfo DateTimeFormatInfoObject { get; set; }
Property Value
Type Description
System.Globalization.DateTimeFormatInfo
Remarks

This value is initially set from the System.Globalization.DateTimeFormatInfo.CurrentInfo and can be changed based on your requirements.

DecimalSeparator

Gets / sets the character to use when a decimal separator position is specified.

Declaration
public char DecimalSeparator { get; set; }
Property Value
Type Description
System.Char
Remarks

This value is initially set from the System.Globalization.NumberFormatInfo and can be changed based on your requirements or based on the locale.

FormattedText

Returns the formatted text with the formatting.

Declaration
public string FormattedText { get; }
Property Value
Type Description
System.String
Remarks

For example, if the text in the MaskedEditBox is (999)999-9999, the FormattedText property will give (999)999-9999.

InputMode

Gets / sets the input mode of the control.

Declaration
public MaskInputMode InputMode { get; set; }
Property Value
Type Description
MaskInputMode
Remarks

The InputMode defines the behavior of the MaskedEditBox to accommodate specialized input for numbers etc.

Lines

See Lines property. The MaskedEditBox does not support multiline controls.

Declaration
public string[] Lines { get; set; }
Property Value
Type Description
System.String[]

Mask

Use this property to define the mask string for the MaskedEditBox control.

Declaration
public string Mask { get; set; }
Property Value
Type Description
System.String
Remarks

The control can distinguish between numeric and alphabetic characters for validation, but cannot check for valid content, such as the correct month or time of day.

MaskDescription
Empty String(Default) No mask. Acts like a text box.
##-???-##Medium date (US). Example: 17-Apr-02
##-##-##Short date (US). Example: 04-17-02
##:## ??Medium time. Example: 10:14 PM
##:##Short time. Example: 22:14

The input mask can consist of the following characters.

Mask characterDescription
#Digit placeholder.
.Decimal placeholder. The actual character used is the one specified as the decimal placeholder in your international settings. This character is treated as a literal for masking purposes.
,Thousands separator. The actual character used is the one specified as the thousands separator in your international settings. This character is treated as a literal for masking purposes.
:Time separator. The actual character used is the one specified as the time separator in your international settings. This character is treated as a literal for masking purposes.
/Date separator. The actual character used is the one specified as the date separator in your international settings. This character is treated as a literal for masking purposes.
\Treat the next character in the mask string as a literal. This allows you to include the '#', &, 'A', and '?' characters in the mask. This character is treated as a literal for masking purposes.
&Character placeholder. Valid values for this placeholder are ANSI characters in the following ranges: 32-126 and 128-255.
>Convert all the characters that follow to uppercase.
<Convert all the characters that follow to lowercase.
AAlphanumeric character placeholder (entry required). For example: a, z, A Z, 0, or 9.
aAlphanumeric character placeholder (entry optional).
9Digit placeholder (entry optional). For example: 0, 9.
CCharacter or space placeholder (entry optional). This operates exactly like the & placeholder, and ensures compatibility with Microsoft Access.
?Letter placeholder. For example: a z or A Z.
LiteralAll other symbols are displayed as literals; that is, as themselves.

MaxLength

Adjusts the MaxLength property based on the Mask string.

Declaration
public override int MaxLength { set; }
Property Value
Type Description
System.Int32

MaxValue

Gets / sets the Maximum Value that can be set through the MaskedEditBox.

Declaration
public decimal MaxValue { get; set; }
Property Value
Type Description
System.Decimal
Remarks

This value is enforced only if the UsageMode property is set to Numeric. The mask string should be set to contain numeric characters. All literal characters will be ignored while computing the value of the contents of the MaskedEditBox. The default value is set to System.Decimal.MaxValue.

MinValue

Gets / sets the Minimum Value that can be set through the MaskedEditBox.

Declaration
public decimal MinValue { get; set; }
Property Value
Type Description
System.Decimal
Remarks

This value is enforced only if the UsageMode property is set to Numeric. The mask string should be set to contain numeric characters. All literal characters will be ignored while computing the value of the contents of the MaskedEditBox. The default value is set to System.Decimal.MaxValue.

Modified

Indicates whether TextBox content is modified, when Mask is used.

Declaration
public bool Modified { get; set; }
Property Value
Type Description
System.Boolean

Multiline

See Multiline property. The MaskedEditBox does not support multiline controls.

Declaration
public override bool Multiline { get; set; }
Property Value
Type Description
System.Boolean

NumberFormatInfoObject

Gets / sets the System.Globalization.NumberFormatInfo provides the necessary globalization information for the properties that rely on these settings.

Declaration
public NumberFormatInfo NumberFormatInfoObject { get; set; }
Property Value
Type Description
System.Globalization.NumberFormatInfo
Remarks

This value is initially set from the System.Globalization.NumberFormatInfo.CurrentInfo and can be changed based on your requirements.

PaddingCharacter

Gets / sets the character that will be used instead of mask characters when the mask position has not been filled when the Text property is accessed.

Declaration
public char PaddingCharacter { get; set; }
Property Value
Type Description
System.Char
Remarks

The default value for the prompt character is set to '-'.

PaddingCharacterInt

Gets / sets the integer version of the PaddingCharacter.

Declaration
public int PaddingCharacterInt { get; set; }
Property Value
Type Description
System.Int32
Remarks

This will not be visible through the designer. Can be set through code. This will be persisted by the designer.

PassivePromptCharacter

Gets / sets the character that will be used instead of mask characters when the mask position has not been filled (when the control does not have the focus).

Declaration
public char PassivePromptCharacter { get; set; }
Property Value
Type Description
System.Char
Remarks

The default value for the prompt character is set to '\0'.

PassivePromptCharacterInt

Gets / sets the integer version of the PassivePromptCharacter.

Declaration
public int PassivePromptCharacterInt { get; set; }
Property Value
Type Description
System.Int32
Remarks

This will not be visible through the designer. Can be set through code. This will be persisted by the designer.

PositionAt

Declaration
public SpecialCursorPosition PositionAt { get; set; }
Property Value
Type Description
SpecialCursorPosition

PositionAtDecimal

Indicates whether the cursor is to be positioned at the decimal separator (if any) when the control receives focus.

Declaration
[Obsolete]
public bool PositionAtDecimal { get; set; }
Property Value
Type Description
System.Boolean
Remarks

The value will be False by default.

PromptCharacter

Gets / sets the character that will be used instead of mask characters when the mask position has not been filled.

Declaration
public char PromptCharacter { get; set; }
Property Value
Type Description
System.Char
Remarks

The default value for the prompt character is set to '-'.

PromptCharacterInt

Gets / sets the integer version of the PromptCharacter.

Declaration
public int PromptCharacterInt { get; set; }
Property Value
Type Description
System.Int32
Remarks

This will not be visible through the designer. Can be set through code. This will be persisted by the designer.

PullCharOnDelete

Pulls the next data position on delete, pays attention to the mask.

Declaration
public bool PullCharOnDelete { get; set; }
Property Value
Type Description
System.Boolean

ScrollBars

See ScrollBarsproperty. The MaskedEditBox does not support multiline controls.

Declaration
public ScrollBars ScrollBars { get; set; }
Property Value
Type Description
System.Windows.Forms.ScrollBars

Sequentially

Gets or sets a value indicating whether the control use sequentially display mask's characters.

Declaration
public bool Sequentially { get; set; }
Property Value
Type Description
System.Boolean

SpecialCultureValue

Gets / sets the mode for the cultures.

Declaration
public SpecialCultureValues SpecialCultureValue { get; set; }
Property Value
Type Description
SpecialCultureValues

Text

Overrides the System.Windows.Forms.TextBox.Text property.

Declaration
public override string Text { get; set; }
Property Value
Type Description
System.String
Remarks

This method is overriden in order to intercept and normalize external text that is not in a format acceptable to the MaskedEditBox. This property value will not be persisted in the designer. Set the Text property after initialization through code or use the SetInitialText method to set the value without raising the TextChanged event.

ThousandSeparator

Gets / sets the character to use when a thousands separator position is specified.

Declaration
public char ThousandSeparator { get; set; }
Property Value
Type Description
System.Char
Remarks

This value is initially set from the System.Globalization.NumberFormatInfo and can be changed based on your requirements or based on the locale.

TimeSeparator

Gets / sets the character to use when a time separator position is specified.

Declaration
public char TimeSeparator { get; set; }
Property Value
Type Description
System.Char
Remarks

This value is initially set from the System.Globalization.DateTimeFormatInfo and can be changed based on your requirements or based on the locale.

UsageMode

Gets / sets the usage mode for the MaskedEditBox.

Declaration
public MaskedUsageMode UsageMode { get; set; }
Property Value
Type Description
MaskedUsageMode
Remarks

The UsageMode defines the behavior of the MaskedEditBox to accomodate specialized input for numbers.

UseLocaleDefault

Indicates whether the individual globalization property changes are to be ignored. If set to True, the individual values will be ignored and the locale default will be used.

Declaration
public bool UseLocaleDefault { get; set; }
Property Value
Type Description
System.Boolean

UseUserOverride

The UseUserOverride parameter for CultureInfo.

Declaration
public bool UseUserOverride { get; set; }
Property Value
Type Description
System.Boolean

WordWrap

See WordWrapproperty. The MaskedEditBox does not support multiline controls.

Declaration
public bool WordWrap { get; set; }
Property Value
Type Description
System.Boolean

Methods

ApplyCasing(Char, CasingNormalize)

Changes the character case according to the casingType passed in and returns the character with the correct casing. Use with the special masks for upper case and lower case.

Declaration
protected char ApplyCasing(char currentChar, CasingNormalize casingType)
Parameters
Type Name Description
System.Char currentChar

The current character.
CasingNormalize casingType

The casing change to be applied.
Returns
Type Description
System.Char

ApplyMaskLogic(String, ref String)

Applies the masking rules and prepares the display string based on the mask string.

Declaration
protected void ApplyMaskLogic(string maskStringIn, ref string displayString)
Parameters
Type Name Description
System.String maskStringIn

The mask string.
System.String displayString

The display string.
Remarks

You will not need to call this method directly. It is invoked by by methods that need to refresh the display.

ApplyRightToLeft()

Applies RightToLeft based on the current culture.

Declaration
protected void ApplyRightToLeft()

ApplySpecialMasks(Int32, Char)

Applies the special masks to the current character - this is for the upper case and lower case masks that are not part of the mask string.

Declaration
protected char ApplySpecialMasks(int currentPosition, char currentChar)
Parameters
Type Name Description
System.Int32 currentPosition
System.Char currentChar
Returns
Type Description
System.Char

CheckMinMax(String, Boolean)

Declaration
protected bool CheckMinMax(string changedString, bool ignoreLength)
Parameters
Type Name Description
System.String changedString
System.Boolean ignoreLength
Returns
Type Description
System.Boolean

Clear()

Clears the mask edit back to its initial state.

Declaration
public void Clear()

Copy()

Copies the content of the MaskEditBox to the clipboard.

Declaration
public void Copy()
Remarks

The ClipMode property dictates what gets copied. For example, if the content of MaskedEditBox is (919)481 1974, the following will be the strings copied to the clipboard depending on the ClipMode property:

ClipModes.IncludeLiterals - (919)481 1974 ClipModes.ExcludeLiterals - 9194811974

CreateAccessibilityInstance()

Declaration
protected override AccessibleObject CreateAccessibilityInstance()
Returns
Type Description
System.Windows.Forms.AccessibleObject
Overrides

Cut()

Cuts data from the MaskedEditBox and pastes it into the clipboard.

Declaration
public void Cut()
Remarks

The MaskedEditBox deletes the selected text in this case and then copies the deleted text to the clipboard. The ClipMode property dictates whether the literal characters are copied to the clipboard or not.

Dispose(Boolean)

Cleans up any resources being used.

Declaration
protected override void Dispose(bool disposing)
Parameters
Type Name Description
System.Boolean disposing
Overrides

EndInit()

Signals the object that the initialization is completed.

Declaration
public override void EndInit()
Overrides

ExtractMaskValues(String)

Extracts the mask values from the mask string that was input by the user and initializes the internal variables that will be used in applying the mask logic.

Declaration
protected string ExtractMaskValues(string maskIn)
Parameters
Type Name Description
System.String maskIn

The mask string input by the user.
Returns
Type Description
System.String

The extracted mask string.
Remarks

The mask string is split up into three different types of characters for applying the masking logic - they are literals, special masks (> and <) and other masks.

> and < are treated as special masks because they do not occupy a position by themselves but dictate the formatting of other adjoining characters.

GetControlName(String)

Helps to apply the ControlName settings in control.

Declaration
public override string GetControlName(string controlName)
Parameters
Type Name Description
System.String controlName

Name of the Control.
Returns
Type Description
System.String
Overrides

GetDataGroupValue(MaskedEditDataGroupInfoCollection, Int32)

Returns the value of a DataGroup as a string.

Declaration
public string GetDataGroupValue(MaskedEditDataGroupInfoCollection currentDataGroups, int index)
Parameters
Type Name Description
MaskedEditDataGroupInfoCollection currentDataGroups
System.Int32 index
Returns
Type Description
System.String

GetDataGroupValue(String, MaskedEditDataGroupInfoCollection, Int32)

Overloaded. Returns the value of a DataGroup as a string.

Declaration
public string GetDataGroupValue(string formttedText, MaskedEditDataGroupInfoCollection currentDataGroups, int index)
Parameters
Type Name Description
System.String formttedText
MaskedEditDataGroupInfoCollection currentDataGroups
System.Int32 index
Returns
Type Description
System.String

GetDecimalValue(String)

Returns the decimal value of the displayed text.

Declaration
protected decimal GetDecimalValue(string currentDisplayText)
Parameters
Type Name Description
System.String currentDisplayText

The currently displayed text.
Returns
Type Description
System.Decimal

The decimal value.

GetMaskCharValue(Char)

Looks up the mask character in the mask list and returns the index so that the masking logic knows what to do with it.

Declaration
protected int GetMaskCharValue(char charIn)
Parameters
Type Name Description
System.Char charIn

The character to be identified.
Returns
Type Description
System.Int32

The index to the mask in the MaskedEditBox.maskList collection.
Remarks

This is a helper method that takes a character and looks up the character in the list of recognized mask characters and returns the result.

GetNextDataPos(Int32)

This method is a helper method for getting the next available data entry position.

Declaration
protected int GetNextDataPos(int currentPosition)
Parameters
Type Name Description
System.Int32 currentPosition

The current position. Checks from here onward.
Returns
Type Description
System.Int32

Returns the next available position.

GetNumericText(String)

Returns the numeric text.

Declaration
protected string GetNumericText(string currentText)
Parameters
Type Name Description
System.String currentText

The current text.
Returns
Type Description
System.String

The numeric text.

GetPrevDataPos(Int32)

This method is a helper method for getting the next available data entry position(backward).

Declaration
protected int GetPrevDataPos(int currentPosition)
Parameters
Type Name Description
System.Int32 currentPosition

The current position. Checks from here backward.
Returns
Type Description
System.Int32

The next available position(backward).

GetPrevDataPos(Int32, Boolean)

Returns the previous data entry position.

Declaration
protected int GetPrevDataPos(int currentPosition, bool bUnfilled)
Parameters
Type Name Description
System.Int32 currentPosition

The current position.
System.Boolean bUnfilled

Indicates whether the new position has to be unfilled.
Returns
Type Description
System.Int32

The new position.

HandleBackspaceKey()

Indicates whether the backspace key has been pressed.

Declaration
protected bool HandleBackspaceKey()
Returns
Type Description
System.Boolean

HandleCharacterInput(Char)

Handles a character input.

Declaration
protected bool HandleCharacterInput(char charInput)
Parameters
Type Name Description
System.Char charInput

The character that was input.
Returns
Type Description
System.Boolean

True if the character was successfully inserted.

HandleDecimalKey()

This method is invoked when the decimal key is pressed.

Declaration
protected bool HandleDecimalKey()
Returns
Type Description
System.Boolean

True if the key is handled; False otherwise.
Remarks

The defined behavior for this key is to jump to the position immediately after the decimal position.

HandleDeleteKey()

Indicates whether the delete key has been pressed.

Declaration
protected bool HandleDeleteKey()
Returns
Type Description
System.Boolean

InsertChar(Int32, Char, Boolean)

Inserts a new character into the displayed text.

Declaration
protected string InsertChar(int startPosition, char newChar, bool updateDisplay)
Parameters
Type Name Description
System.Int32 startPosition

The start position to insert the character.
System.Char newChar

The new character to be inserted.
System.Boolean updateDisplay

Indicates whether the display is to be updated.
Returns
Type Description
System.String

The changed text.

InsertChar(String, Int32, Char, Boolean)

Inserts a new character into the displayed text.

Declaration
protected string InsertChar(string currentDisplayText, int startPosition, char newChar, bool updateDisplay)
Parameters
Type Name Description
System.String currentDisplayText

The current display text.
System.Int32 startPosition

The start position to insert the character.
System.Char newChar

The new character to be inserted.
System.Boolean updateDisplay

Indicates whether the display is to be updated.
Returns
Type Description
System.String

The changed text.

IsCharValid(Int32, Char)

Indicates whether the character is valid for this position based on the mask.

Declaration
protected bool IsCharValid(int currentPosition, char currentChar)
Parameters
Type Name Description
System.Int32 currentPosition

The current position.
System.Char currentChar

The current character.
Returns
Type Description
System.Boolean

True if the character is acceptable; False otherwise.

IsLiteralCharacter(Char)

Indicates whether the in parameter is a literal character.

Declaration
protected bool IsLiteralCharacter(char charIn)
Parameters
Type Name Description
System.Char charIn

The character to check.
Returns
Type Description
System.Boolean

True if the input character is a mask character.
Remarks

All characters that are accepted as input are subjected to this check.

IsMaskActive()

If the mask string is empty, we do not apply any rules. This helper function checks whether the mask is active.

Declaration
protected bool IsMaskActive()
Returns
Type Description
System.Boolean

True if the mask is active; False otherwise.

IsMaskPositionFilled(String, Int32)

Declaration
protected bool IsMaskPositionFilled(string currentString, int index)
Parameters
Type Name Description
System.String currentString
System.Int32 index
Returns
Type Description
System.Boolean

MoveCursorPosition(Int32, Int32, Boolean)

Moves the cursor position depending on the action.

Declaration
protected int MoveCursorPosition(int currentPosition, int direction, bool selected)
Parameters
Type Name Description
System.Int32 currentPosition

The current position of the cursor.
System.Int32 direction

The direction which the cursor needs to be moved.
System.Boolean selected

Boolean value specifying if there is selected text.
Returns
Type Description
System.Int32

The position of the cursor after setting it.
Remarks

The MaskedEditBox control automatically adjusts its cursor position when there is a change in the content of the text box.

NormalizeCasing(Char, CasingNormalize)

Applies the current CharacterCasing settings in effect for this textbox.

Declaration
protected char NormalizeCasing(char currentChar, CasingNormalize casingType)
Parameters
Type Name Description
System.Char currentChar

The current character.
CasingNormalize casingType

The casing change to be applied.
Returns
Type Description
System.Char

The changed character.

OnClick(EventArgs)

Overrides the OnClick method.

Declaration
protected override void OnClick(EventArgs arg)
Parameters
Type Name Description
System.EventArgs arg

The event data.
Remarks

Position the cursor when the user clicks inside the control.

OnEnter(EventArgs)

Overrides the System.Windows.Forms.Control.OnEnter(System.EventArgs) method.

Declaration
protected override void OnEnter(EventArgs arg)
Parameters
Type Name Description
System.EventArgs arg

The event data.
Remarks

This method is overriden in order to refresh the display between the passive and active prompt characters.

OnLeave(EventArgs)

Overrides the System.Windows.Forms.Control.OnLostFocus(System.EventArgs) method.

Declaration
protected override void OnLeave(EventArgs arg)
Parameters
Type Name Description
System.EventArgs arg

The event data.
Remarks

This method is overriden in order to refresh the display between the passive and active prompt characters.

OnMaskCustomValidate(MaskCustomValidateArgs)

Raises the MaskCustomValidate event.

Declaration
protected void OnMaskCustomValidate(MaskCustomValidateArgs args)
Parameters
Type Name Description
MaskCustomValidateArgs args

The event data.

OnMaskSatisfied(EventArgs)

Invokes the MaskSatisfied event.

An EventArgs that contains the event data. The OnMaskSatisfied method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class.
note

Inheritors: When overriding OnMaskSatisfied in a derived class, be sure to call the base class's OnMaskSatisfied method so that registered delegates receive the event.
Declaration
protected virtual void OnMaskSatisfied(EventArgs args)
Parameters
Type Name Description
System.EventArgs args

OnTextChanged(EventArgs)

Overrides and prevents the event from being raised if the control is being initialized.

Declaration
protected override void OnTextChanged(EventArgs arg)
Parameters
Type Name Description
System.EventArgs arg

The event args.
Overrides

OnValidating(CancelEventArgs)

Overrides System.Windows.Forms.Control.OnValidating(System.ComponentModel.CancelEventArgs) method.

Declaration
protected override void OnValidating(CancelEventArgs args)
Parameters
Type Name Description
System.ComponentModel.CancelEventArgs args

The event data.
Remarks

Raises the ValidationError event when there is unacceptable text in the control.

OnValidationError(ValidationErrorArgs)

Invokes the ValidationError event.

A ValidationErrorEventArgs that contains the event data. The OnValidationError method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class.
note

Inheritors: When overriding OnValidationError in a derived class, be sure to call the base class's OnValidationError method so that registered delegates receive the event.
Declaration
protected virtual void OnValidationError(ValidationErrorArgs args)
Parameters
Type Name Description
ValidationErrorArgs args

Paste()

Handles the pasting of data from the clipboard into the MaskededitBox control.

Declaration
public void Paste()
Remarks

The method takes into account the nature of the text in the clipboard and tries to normalize the text. It will accomodate as much as possible depending on the current length of the text and the total length allowed. If text with acceptable and unacceptable characters are found in the clipboard, the unacceptable data is omitted when the data is inserted.

ProcessKeyEventArgs(ref Message)

Overrides to suppress KeyPress. Only the KeyPress event is raised - no other processing is done.

Declaration
protected override bool ProcessKeyEventArgs(ref Message m)
Parameters
Type Name Description
System.Windows.Forms.Message m

The message.
Returns
Type Description
System.Boolean

True if the message is a KeyPress; otherwise the base class handles this.

ProcessKeyMessage(ref Message)

Intercepts the Key messages.

Declaration
protected override bool ProcessKeyMessage(ref Message m)
Parameters
Type Name Description
System.Windows.Forms.Message m

The message data.
Returns
Type Description
System.Boolean

True if the key is handled; False otherwise.

RaiseMaskSatisfied()

This method raises the MaskSatisfied event.

Declaration
protected void RaiseMaskSatisfied()
Remarks

See the OnMaskSatisfied(EventArgs) method for more information.

RaiseValidationError(String, Int32)

This method raises the ValidationError event.

Declaration
protected void RaiseValidationError(string invalidText, int startPosition)
Parameters
Type Name Description
System.String invalidText

The text that was input.
System.Int32 startPosition

The start position of the error.
Remarks

See the OnValidationError(ValidationErrorArgs) method for more information.

RefreshDisplay()

Refreshes the display based on the current display characteristics.

Declaration
public void RefreshDisplay()
Remarks

Changes made to the Mask property or any other property that affects the display of the formatted string will be picked up by invoking this method.

RefreshDisplay(String, Boolean)

Declaration
protected void RefreshDisplay(string dispString, bool updateUndo)
Parameters
Type Name Description
System.String dispString
System.Boolean updateUndo

RefreshPromptCharacter()

Refreshes the display with the current prompt character.

Declaration
protected void RefreshPromptCharacter()
Remarks

This method changes the display based on the new prompt character by replacing the old prompt character with the new prompt character.

RemoveFromCustomFilledList(Int32)

Declaration
protected void RemoveFromCustomFilledList(int index)
Parameters
Type Name Description
System.Int32 index

RemoveText(Int32, Int32)

Removes the selected text.

Declaration
protected string RemoveText(int startPosition, int endPosition)
Parameters
Type Name Description
System.Int32 startPosition

The start position of the selection.
System.Int32 endPosition

The end position of the selection.
Returns
Type Description
System.String

The modified string.

RemoveText(String, Int32, Int32)

Removes the text selected or specified by the parameters.

Declaration
protected string RemoveText(string currentDisplayText, int startPosition, int endPosition)
Parameters
Type Name Description
System.String currentDisplayText

The current string to be modified.
System.Int32 startPosition

The start position of the selection.
System.Int32 endPosition

The end position of the selection.
Returns
Type Description
System.String

The modified string.

RemoveTextWithinGroup(String, Int32, Int32)

Removes the text selected or specified by the parameters within a group. In this case, a group is defined as an area separated by a DecimalSeparator, Date Separator or Time Separator.

Declaration
protected string RemoveTextWithinGroup(string currentDisplayText, int startPosition, int endPosition)
Parameters
Type Name Description
System.String currentDisplayText

The current string to be modified.
System.Int32 startPosition

The start position of the selection.
System.Int32 endPosition

The end position of the selection.
Returns
Type Description
System.String

The modified string.

Reset()

Resets the MaskedEditBox control to its initial position.

Declaration
public void Reset()
Remarks

Invoke this method when you need to reinitialize the MaskededitBox. The Mask property will not be lost because of calling this method.

ResetBackColor()

Resets BackColor of the control to its default value.

Declaration
public override void ResetBackColor()

SetCustomFilledPosition(Char, Int32)

Declaration
protected void SetCustomFilledPosition(char newChar, int index)
Parameters
Type Name Description
System.Char newChar
System.Int32 index

SetExternalText(String, Int32, Boolean, Boolean)

Sets external text from the clipboard to the MaskedEditBox.

Declaration
protected bool SetExternalText(string externalText, int beginPos, bool insertMode, bool ignorePromptCharacters)
Parameters
Type Name Description
System.String externalText

The text to be pasted.
System.Int32 beginPos

The beginning position.
System.Boolean insertMode

Indicates whether the text is to be inserted.
System.Boolean ignorePromptCharacters

Indicates whether to ignore prompt characters.
Returns
Type Description
System.Boolean

True if the text was set successfully; False otherwise.

SetInitialText(String)

Sets the text property of the MaskedEditBox without raising the TextChanged event.

Declaration
public void SetInitialText(string newText)
Parameters
Type Name Description
System.String newText

The new text string.
Remarks

This method is provided as an alternative to being able to set the Text property through the designer.

SetSelection(Int32, Int32)

Sets the cursor and also selects text for the specified length based on the parameters passed in.

Declaration
protected void SetSelection(int startPosition, int selectionLength)
Parameters
Type Name Description
System.Int32 startPosition

The beginning position for the selection.
System.Int32 selectionLength

The length of the selection.

SetTextBoxText(String)

Declaration
protected void SetTextBoxText(string text)
Parameters
Type Name Description
System.String text

Undo()

This method will Undo the previous operation.

Declaration
public void Undo()
Remarks

The MaskedEditBox maintains its own undo mechanism.

Validate(Boolean)

Validates the control.

Declaration
public void Validate(bool bRaiseValidationError)
Parameters
Type Name Description
System.Boolean bRaiseValidationError

Specifies if the validation error is to be raised.

Events

MaskCustomValidate

Handle this event to provide custom behavior to any of the mask characters.

Declaration
public event MaskCustomValidateEventHandler MaskCustomValidate
Event Type
Type Description
MaskCustomValidateEventHandler

MaskSatisfied

MaskSatisfied event will be raised when the required fields in a mask have been satisfied after new text has been entered / the text changes.

Declaration
public event EventHandler MaskSatisfied
Event Type
Type Description
System.EventHandler
Remarks

This event will be raised only when there are entries that require input have been filled. This even can be used to move to another control after the mask rules have been satisfied.

PropertyChanged

Property changed event handler.

Declaration
public event PropertyChangedEventHandler PropertyChanged
Event Type
Type Description
System.ComponentModel.PropertyChangedEventHandler

ValidationError

ValidationError event will be raised when an unacceptable character is encountered as input.

Declaration
public event ValidationErrorEventHandler ValidationError
Event Type
Type Description
ValidationErrorEventHandler
Remarks

This event can be handled and you can do your processing based on the information provided. The ValidationErrorEventArgs object will provide the invalid text that was input and also the position within that text where the error occurred.

Explicit Interface Implementations

ISerializable.GetObjectData(SerializationInfo, StreamingContext)

Declaration
void ISerializable.GetObjectData(SerializationInfo info, StreamingContext context)
Parameters
Type Name Description
System.Runtime.Serialization.SerializationInfo info
System.Runtime.Serialization.StreamingContext context

Implements

System.ComponentModel.ISupportInitialize
System.Runtime.Serialization.ISerializable

Extension Methods