WinForms

Upgrade Guide User Guide Demos Support Forums Download
  • Upgrade Guide
  • User Guide
  • Demos
  • Support
  • Forums
  • Download
Class MaskedEditBox - WindowsForms API Reference | Syncfusion

    Show / Hide Table of Contents

    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
    IThemeProvider
    System.ComponentModel.ISupportInitialize
    IVisualStyle
    System.Runtime.Serialization.ISerializable
    Inherited Members
    TextBoxExt.OnThemeNameChanged(String)
    TextBoxExt.ApplyScaleToControl(Single)
    TextBoxExt.OnGotFocus(EventArgs)
    TextBoxExt.GetActiveThemeName()
    TextBoxExt.OnMaximumSizeChanged(EventArgs)
    TextBoxExt.OnMouseDown(MouseEventArgs)
    TextBoxExt.OnMouseEnter(EventArgs)
    TextBoxExt.OnMouseLeave(EventArgs)
    TextBoxExt.DefWndProc(Message)
    TextBoxExt.OnFontChanged(EventArgs)
    TextBoxExt.OnMinimumSizeChanged(EventArgs)
    TextBoxExt.OnCharacterCasingChanged(EventArgs)
    TextBoxExt.OnBorderSidesChanged(EventArgs)
    TextBoxExt.OnBorderColorChanged(EventArgs)
    TextBoxExt.OnBorder3DStyleChanged(EventArgs)
    TextBoxExt.RaiseThemeChanged(Object, ThemeChangedEventArgs)
    TextBoxExt.OnCanApplyThemeChanged(Boolean)
    TextBoxExt.OnCanOverrideStyleChanged(Boolean)
    TextBoxExt.OnThemesEnabledChanged(EventArgs)
    TextBoxExt.OnParentChanged(EventArgs)
    TextBoxExt.OnEnabledChanged(EventArgs)
    TextBoxExt.OnPaint(PaintEventArgs)
    TextBoxExt.OnHandleCreated(EventArgs)
    TextBoxExt.OnHandleDestroyed(EventArgs)
    TextBoxExt.OnMultilineChanged(EventArgs)
    TextBoxExt.WndProc(Message)
    TextBoxExt.NCOverflowIndicatorPaint(Graphics, Rectangle, Rectangle)
    TextBoxExt.OnSizeChanged(EventArgs)
    TextBoxExt.OnBorderStyleChanged(EventArgs)
    TextBoxExt.OnLostFocus(EventArgs)
    TextBoxExt.BeginInit()
    TextBoxExt.IThemeProvider.BaseThemeName
    TextBoxExt.ThemeStyle
    TextBoxExt.ControlName
    TextBoxExt.IsVisualStyleEnabled
    TextBoxExt.BeforeTouchSize
    TextBoxExt.EnableTouchMode
    TextBoxExt.CreateParams
    TextBoxExt.Metrocolor
    TextBoxExt.FocusBorderColor
    TextBoxExt.UseBorderColorOnFocus
    TextBoxExt.ShowOverflowIndicatorToolTip
    TextBoxExt.OverflowIndicatorToolTipText
    TextBoxExt.ShowOverflowIndicator
    TextBoxExt.DrawActiveWhenDisabled
    TextBoxExt.BorderSides
    TextBoxExt.Border3DStyle
    TextBoxExt.BorderColor
    TextBoxExt.OverflowIndicatorToolTip
    TextBoxExt.ThemesEnabled
    TextBoxExt.MaximumSize
    TextBoxExt.MinimumSize
    TextBoxExt.CharacterCasing
    TextBoxExt.CornerRadius
    TextBoxExt.NearImage
    TextBoxExt.ThemeName
    TextBoxExt.FarImage
    TextBoxExt.CanOverrideStyle
    TextBoxExt.CanApplyTheme
    TextBoxExt.Style
    TextBoxExt.IVisualStyle.VisualTheme
    TextBoxExt.Office2010ColorScheme
    TextBoxExt.Office2010ColorTable
    TextBoxExt.Office2007ColorScheme
    TextBoxExt.Office2007ColorTable
    TextBoxExt.Initializing
    TextBoxExt.BorderSidesChanged
    TextBoxExt.Border3DStyleChanged
    TextBoxExt.ThemeNameChanged
    TextBoxExt.BorderColorChanged
    TextBoxExt.ThemesEnabledChanged
    TextBoxExt.MaximumSizeChanged
    TextBoxExt.MinimumSizeChanged
    TextBoxExt.CharacterCasingChanged
    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
    TextBoxExt.CreateAccessibilityInstance()

    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
    TextBoxExt.Dispose(Boolean)

    EndInit()

    Signals the object that the initialization is completed.

    Declaration
    public override void EndInit()
    Overrides
    TextBoxExt.EndInit()

    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
    TextBoxExt.GetControlName(String)

    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
    TextBoxExt.OnTextChanged(EventArgs)

    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

    IThemeProvider
    System.ComponentModel.ISupportInitialize
    IVisualStyle
    System.Runtime.Serialization.ISerializable
    Back to top Generated by DocFX
    Copyright © 2001 - 2021 Syncfusion Inc. All Rights Reserved