CMFCMaskedEdit Class

The CMFCMaskedEdit class supports a masked edit control, which validates user input against a mask and displays the validated results according to a template.

Syntax

class CMFCMaskedEdit : public CEdit

Members

Public Constructors

Public Methods

Protected Methods

Remarks

Perform the following steps to use the CMFCMaskedEdit control in your application:

1. Embed a CMFCMaskedEdit object into your window class.

2. Call the CMFCMaskedEdit::EnableMask method to specify the mask.

3. Call the CMFCMaskedEdit::SetValidChars method to specify the list of valid characters.

4. Call the CMFCMaskedEdit::SetWindowText method to specify the default text for the masked edit control.

5. Call the CMFCMaskedEdit::GetWindowText method to retrieve the validated text.

If you do not call one or more methods to initialize the mask, valid characters, and default text, the masked edit control behaves just as the standard edit control behaves.

Example

The following example demonstrates how to set up a mask (for example a phone number) by using the EnableMask method to create the mask for the masked edit control, the SetValidChars method to specify a string of valid characters that the user can enter, and SetWindowText method to display a prompt in the masked edit control. This example is part of the New Controls sample.

CMFCMaskedEdit m_wndMaskEdit1;
CMFCMaskedEdit m_wndMaskEdit2;
CMFCMaskedEdit m_wndMaskEdit3;
CMFCMaskedEdit m_wndMaskEdit4;
CMFCMaskedEdit m_wndMaskEdit5;

CString m_strValue1;
CString m_strValue2;
CString m_strValue3;
CString m_strValue4;
CString m_strValue5;

BOOL CPage4::OnInitDialog()
{
   CMFCPropertyPage::OnInitDialog();

   // Mask 1: phone number
   m_wndMaskEdit1.EnableMask(_T(" ddd  ddd dddd"), // The mask string
                             _T("(___) ___-____"), // Literal, "_" char = character entry
                             _T(' '));             // Default char
   m_wndMaskEdit1.SetValidChars(NULL);             // Valid string characters
   m_wndMaskEdit1.SetWindowText(_T("(123) 123-1212"));

   // Mask 2: State, Zip Code
   m_wndMaskEdit2.EnableMask(_T("       cc       ddddd-dddd"), // The mask string
                             _T("State: __, Zip: _____-____"), // Literal, "_" char = character entry
                             _T(' '));                         // Backspace replace char
   m_wndMaskEdit2.SetValidChars(NULL);                         // Valid string characters
   m_wndMaskEdit2.SetWindowText(_T("State: NY, Zip: 12345-6789"));
   // Mask 3: serial code
   m_wndMaskEdit3.EnableMask(_T("     AAAA AAAA AAAA AAAA"), // The mask string
                             _T("S/N: ____-____-____-____"), // Literal, "_" char = character entry
                             _T('_'));                       // Backspace replace char
   m_wndMaskEdit3.SetValidChars(NULL);                       // Valid string characters
   m_wndMaskEdit3.SetWindowText(_T("S/N: FPR5-5678-1234-8765"));

   // Mask 4: 0xFFFF
   m_wndMaskEdit4.EnableMask(_T("  AAAA"),                     // The mask string
                             _T("0x____"),                     // Literal, "_" char = character entry
                             _T('_'));                         // Backspace replace char
   m_wndMaskEdit4.SetValidChars(_T("1234567890ABCDEFabcdef")); // Valid string characters
   m_wndMaskEdit4.SetWindowText(_T("0x01AF"));

   // Mask 5: digits only
   m_wndMaskEdit5.DisableMask();                   // Don't use the mask
   m_wndMaskEdit5.SetValidChars(_T("1234567890")); // Valid string characters
   m_wndMaskEdit5.SetWindowText(_T("1234567890"));

   return TRUE; // return TRUE unless you set the focus to a control
}

void CPage4::OnButtonGet()
{
   m_wndMaskEdit1.GetWindowText(m_strValue1);
   m_wndMaskEdit2.GetWindowText(m_strValue2);
   m_wndMaskEdit3.GetWindowText(m_strValue3);
   m_wndMaskEdit4.GetWindowText(m_strValue4);
   m_wndMaskEdit5.GetWindowText(m_strValue5);
   UpdateData(FALSE);
}

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CEdit

CMFCMaskedEdit

Requirements

Header: afxmaskededit.h

CMFCMaskedEdit::DisableMask

Disables validating user input.

void DisableMask();

Remarks

If user input validation is disabled, the masked edit control behaves like the standard edit control.

CMFCMaskedEdit::EnableGetMaskedCharsOnly

Specifies whether the GetWindowText method retrieves only masked characters.

void EnableGetMaskedCharsOnly(BOOL bEnable=TRUE);

Parameters

bEnable
[in] TRUE to specify that the CMFCMaskedEdit::GetWindowText method retrieve only masked characters; FALSE to specify that the method retrieve the whole text. The default value is TRUE.

Remarks

Use this method to enable retrieving masked characters. Then create a masked edit control that corresponds to the telephone number, such as (425) 555-0187. If you call the GetWindowText method, it returns "4255550187". If you disable retrieving masked characters, the GetWindowText method returns the text that is displayed in the edit control, for example "(425) 555-0187".

CMFCMaskedEdit::EnableMask

Initializes the masked edit control.

void EnableMask(
    LPCTSTR lpszMask,
    LPCTSTR lpszInputTemplate,
    TCHAR chMaskInputTemplate=_T('_'),
    LPCTSTR lpszValid=NULL);

Parameters

lpszMask
[in] A mask string that specifies the type of character that can appear at each position in the user input. The length of the lpszInputTemplate and lpszMask parameter strings must be the same. See the Remarks section for more detail about mask characters.

lpszInputTemplate
[in] A mask template string that specifies the literal characters that can appear at each position in the user input. Use the underscore character ('_') as a character placeholder. The length of the lpszInputTemplate and lpszMask parameter strings must be the same.

chMaskInputTemplate
[in] A default character that the framework substitutes for each invalid character in the user input. The default value of this parameter is underscore ('_').

lpszValid
[in] A string that contains a set of valid characters. NULL indicates that all characters are valid. The default value of this parameter is NULL.

Remarks

Use this method to create the mask for the masked edit control. Derive a class from the CMFCMaskedEdit class and override the CMFCMaskedEdit::IsMaskedChar method to use your own code for custom mask processing.

The following table list the default mask characters:

CMFCMaskedEdit::EnableSelectByGroup

Specifies whether the masked edit control allows the user to select particular groups input, or all input.

void EnableSelectByGroup(BOOL bEnable=TRUE);

Parameters

bEnable
[in] TRUE to select only groups; FALSE to select the whole text. The default value is TRUE.

Remarks

Use this function to specify whether the masked edit control allows a user to select by group or the whole text.

By default, selection by group is enabled. In this case the user can select only continuous groups of valid characters.

For example, you might use the following masked edit control to validate a telephone number:

m_wndMaskEdit.EnableMask(
    _T(" ddd  ddd dddd"),  // Mask string
    _T("(___) ___-____"),  // Template string
    _T(' '));              // Default char

m_wndMaskEdit.SetValidChars(NULL); // All characters are valid.

m_wndMaskEdit.SetWindowText(_T("(425) 555-0187")); // Prompt

If selection by group is enabled, the user can retrieve only the "425", "555", or "0187" string groups. If group selection is disabled the user can retrieve the whole text of the telephone number: "(425) 555-0187".

CMFCMaskedEdit::EnableSetMaskedCharsOnly

Specifies whether the text is validated against only the masked characters, or against the whole mask.

void EnableSetMaskedCharsOnly(BOOL bEnable=TRUE);

Parameters

bEnable
[in] TRUE to validate the user input against only masked characters; FALSE to validate against the whole mask. The default value is TRUE.

CMFCMaskedEdit::GetWindowText

Retrieves validated text from the masked edit control.

int GetWindowText(
    LPTSTR lpszStringBuf,
    int nMaxCount) const;

void GetWindowText(CString& rstrString) const;

Parameters

lpszStringBuf
[out] A pointer to a buffer that receives the text from the edit control.

nMaxCount
[in] The maximum number of characters to receive.

rstrString
[out] A reference to the string object that receives the text from the edit control.

Return Value

The first method overload returns the number of bytes of the string that is copied to the lpszStringBuf parameter buffer; 0 if the masked edit control has no text.

Remarks

This method copies the text from the masked edit control to the lpszStringBuf buffer or the rstrString string.

This method redefines CWnd::GetWindowText.

CMFCMaskedEdit::IsMaskedChar

Called by the framework to validate the specified character against the corresponding mask character.

virtual BOOL IsMaskedChar(
    TCHAR chChar,
    TCHAR chMaskChar) const;

Parameters

chChar
[in] The character to be validated.

chMaskChar
[in] The corresponding character from the mask string.

Return Value

TRUE if the chChar parameter is the type of character permitted by the chMaskChar parameter; otherwise, FALSE.

Remarks

Override this method to validate input characters on your own. For more information about mask characters, see the CMFCMaskedEdit::EnableMask method.

CMFCMaskedEdit::SetValidChars

Specifies a string of valid characters that the user can enter.

void SetValidChars(LPCTSTR lpszValid=NULL);

Parameters

lpszValid
[in] A string that contains the set of valid input characters. NULL means that all characters are valid. The default value of this parameter is NULL.

Remarks

Use this method to define a list of valid characters. If an input character is not in this list, masked edit control will not accept it.

The following code example accepts only hexadecimal numbers.

//Mask: 0xFFFF
m_wndMaskEdit.EnableMask(
    _T(" AAAA"),                // The mask string.
    _T("0x____"),               // The literal template string.
    _T('_'));                   // The default character that
                                // replaces the backspace character.
// Valid string characters
m_wndMaskEdit.SetValidChars(_T("1234567890ABCDEFabcdef"));m_wndMaskEdit.SetWindowText(_T("0x01AF"));

CMFCMaskedEdit::SetWindowText

Displays a prompt in the masked edit control.

void SetWindowText(LPCTSTR lpszString);

Parameters

lpszString
[in] Points to a null-terminated string that will be used as a prompt.

Remarks

This method sets the control text.

This method redefines CWnd::SetWindowText.

See also

Hierarchy Chart
Classes
CEdit Class