Home

Windows Controls: Masked Edit Control

   

Introduction to the Masked Edit Control

 

Description

 

By default, the edit control allows (almost) any type of character, including readable and non-readable characters. In the Win32 and the MFC libraries, it can be made to accept only digits. It still lacks some of the customizations that would consist of accepting only some symbols and rejecting others. Instead of writing long code that would take have to analyze complex expressions, the MFC library provides the masked edit control.

The masked edit control is a custom editor that can be made to accept only some characters and to reject some others. It makes it possible to let the user enter only some specific items like a social security number, a telephone number, a date, or a time, etc.

Creating a Masked Edit Control

To visually create a masked edit control, in the Toolbox, click the MFC MaskedEdit Control MFC Masked Edit Control and click the dialog box. The masked edit control is implemented by a class named CMFCMaskedEdit, which is derived from CEdit.

As done for all MFC controls, after visually adding a masked edit control, you should add a member variable for it.

Characteristics of a Masked Edit Control

 

Creating a Mask

The most important characteristic of a masked edit control is the way it allows some characters and rejects some others. This scheme is referred to as its mask. To visually create the mask, you use two steps in the Properties window. The Mask field is used to specify whether to allow letters or digits. The mask uses one or a combination of the following characters:

Character Description
C An alphabetic letter must be entered
D A digit (0, 1, 2, 3, 4, 5, 6, 7, 8, or 9) must be entered
A A letter or a digit can be entered
* A printable symbol (letter, digit, #, $, @, etc) can be entered
c A letter can be entered or the space can be left empty
d A digit can be entered or the space can be left empty
a A letter or a digit can be entered, or the space can be left empty
+ A + or - must be entered

The Input Placeholders

A masked edit control must indicate where the characters must be entered and where empty spaces can be left. To visually created them, in the Properties window click Input Template and type the characters:

Character Name Description
_ Underscore This is used as a placeholder
- Dash This is used as the separator between two sections
  Default Char This is used where no character from the mask  would be used. The default is an empty space

Besides the underscore, the dash, or an empty space, you can enter any character other than A, a, C, c, D, d, *, or +. Any character would be kept "as is".

To actually visually create a mask, you use a combination of the Mask and the Input Template fields in the Properties window. Here is an example:

Masked Edit Control

Examples of masks are:

Input Template Mask Description
(___) ___-____  ddd ddd dddd U.S. and Canada telephone number
___-___-____  ddd ddd dddd U.S. and Canada telephone number
___-__-____  ddd dd dddd U.S. Social Security Number

Programmatically Creating a Mask

To let you programmatically create a mask and its placeholders, the CMFCMaskedEdit class is equipped with the EnableMask() member function. Its syntax is:

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

This member function takes 4 arguments with the first two being required. The first argument is the mask of the control. The second argument creates the placeholder(s). Both arguments play the same roles as the Mask and the Input Template fields of the Properties window.

After visually or programmatically creating a mask, the control would impose its rules to the user. If you want to ignore the mask and make the masked edit control behave like a regular edit box, call the DisableMask() member function of the CMFCMaskedEdit class. Its syntax is:

void DisableMask();

Setting a Default String to a Masked Edit Control

When a masked edit control displays, the user may not know what types of values to enter. One way you can address this issue is to present a default value in the control. To do this, call the SetWindowText() member function of the CMFCMaskedEdit class. Its syntax is:

void SetWindowText(LPCTSTR lpszString);

Here is an example of calling it:

BOOL CExerciseDlg::OnInitDialog()
{
    CDialogEx::OnInitDialog();

    // Set the icon for this dialog.  The framework does this automatically
    //  when the application's main window is not a dialog
    SetIcon(m_hIcon, TRUE);			// Set big icon
    SetIcon(m_hIcon, FALSE);		// Set small icon

    // TODO: Add extra initialization here

    m_TelephoneNumber.SetWindowTextW(L"(000) 000-0000");

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

Getting the Characters of a Masked Edit Control

After the user has typed a value in the masked edit control, to get that value, you can call the CMFCMaskedEdit::GetWindowTex() member function. It is provided in two versions whose syntaxes are:

int GetWindowText(LPTSTR lpszStringBuf, int nMaxCount) const;
void GetWindowText(CString& rstrString) const;

The first version takes an array of characters and its length as arguments. The second version takes a CString as argument. Here is an example:

void CExerciseDlg::OnBnClickedGetValue()
{
	// TODO: Add your control notification handler code here
	CString strValue;

	m_ShelfNumber.GetWindowText(strValue);
	
	m_Value = strValue;
	UpdateData(FALSE);
}

Masked Edit Control

Getting the Whole Value of a Masked Edit Control

By default, the CMFCMaskedEdit::GetWindowText() member function produces only the characters that a user entered in the control, leaving out the input symbols of the mask. If you want to include those symbols in the result, call the EnableGetMaskedCharsOnly() member function. Its syntax is:

void EnableGetMaskedCharsOnly(BOOL bEnable = TRUE);

This function takes as argument a Boolean value that determines whether to consider or ignore the symbols of the mask. The default value of the argument is TRUE, which means the mask symbols would not be included in the resulting string. If you want to include those symbols, call this member function before calling GetWindowText() and pass the argument as FALSE. Here is an example:

void CExerciseDlg::OnBnClickedGetValue()
{
	// TODO: Add your control notification handler code here
	CString strValue;

	m_ShelfNumber.EnableGetMaskedCharsOnly(FALSE);

	m_ShelfNumber.GetWindowText(strValue);
	m_Value = strValue;
	UpdateData(FALSE);
}

Masked Edit Control

  

 

 
 
     
 

Home Copyright © 2010-2011 FunctionX, Inc.