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
| Name | Description |
|---|---|
CMFCMaskedEdit::CMFCMaskedEdit |
Default constructor. |
CMFCMaskedEdit::~CMFCMaskedEdit |
Destructor. |
Public Methods
| Name | Description |
|---|---|
| CMFCMaskedEdit::DisableMask | Disables validating user input. |
| CMFCMaskedEdit::EnableGetMaskedCharsOnly | Specifies whether the GetWindowText method retrieves only masked characters. |
| CMFCMaskedEdit::EnableMask | Initializes the masked edit control. |
| CMFCMaskedEdit::EnableSelectByGroup | Specifies whether the masked edit control selects particular groups of user input, or all user input. |
| CMFCMaskedEdit::EnableSetMaskedCharsOnly | Specifies whether the text is validated against only masked characters, or against the whole mask. |
CMFCMaskedEdit::GetThisClass |
Used by the framework to obtain a pointer to the CRuntimeClass object that is associated with this class type. |
| CMFCMaskedEdit::GetWindowText | Retrieves validated text from the masked edit control. |
| CMFCMaskedEdit::SetValidChars | Specifies a string of valid characters that the user can enter. |
| CMFCMaskedEdit::SetWindowText | Displays a prompt in the masked edit control. |
Protected Methods
| Name | Description |
|---|---|
| CMFCMaskedEdit::IsMaskedChar | Called by the framework to validate the specified character against the corresponding mask character. |
Remarks
Perform the following steps to use the CMFCMaskedEdit control in your application:
Embed a
CMFCMaskedEditobject into your window class.Call the CMFCMaskedEdit::EnableMask method to specify the mask.
Call the CMFCMaskedEdit::SetValidChars method to specify the list of valid characters.
Call the CMFCMaskedEdit::SetWindowText method to specify the default text for the masked edit control.
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
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:
| Mask Character | Definition |
|---|---|
| D | Digit. |
| d | Digit or space. |
| + | Plus ('+'), minus ('-'), or space. |
| C | Alphabetic character. |
| c | Alphabetic character or space. |
| A | Alphanumeric character. |
| a | Alphanumeric character or space. |
| * | A printable character. |
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.