Classe CMFCMaskedEdit

Artigo
06/16/2023

A classe CMFCMaskedEdit dá suporte a um controle de edição mascarada, que valida a entrada de usuário em uma máscara e exibe os resultados validados de acordo com um modelo.

Sintaxe

class CMFCMaskedEdit : public CEdit

Membros

Construtores públicos

Nome	Descrição
`CMFCMaskedEdit::CMFCMaskedEdit`	Construtor padrão.
`CMFCMaskedEdit::~CMFCMaskedEdit`	Destruidor.

Métodos públicos

Nome	Descrição
CMFCMaskedEdit::DisableMask	Desabilita a validação da entrada do usuário.
CMFCMaskedEdit::EnableGetMaskedCharsOnly	Especifica se o método `GetWindowText` recupera apenas caracteres mascarados.
CMFCMaskedEdit::EnableMask	Inicializa o controle de edição mascarada.
CMFCMaskedEdit::EnableSelectByGroup	Especifica se o controle de edição mascarada seleciona grupos específicos de entrada do usuário ou todas as entradas do usuário.
CMFCMaskedEdit::EnableSetMaskedCharsOnly	Especifica se o texto é validado somente em caracteres mascarados ou em toda a máscara.
`CMFCMaskedEdit::GetThisClass`	Usado pela estrutura para obter um ponteiro para o objeto CRuntimeClass associado a esse tipo de classe.
CMFCMaskedEdit::GetWindowText	Recupera o texto validado do controle de edição mascarada.
CMFCMaskedEdit::SetValidChars	Especifica uma cadeia de caracteres válida que o usuário pode inserir.
CMFCMaskedEdit::SetWindowText	Exibe um prompt no controle de edição mascarada.

Métodos protegidos

Nome	Descrição
CMFCMaskedEdit::IsMaskedChar	Chamado pela estrutura para validar o caractere especificado em relação ao caractere de máscara correspondente.

Comentários

Execute as seguintes etapas para usar a classe CMFCMaskedEdit no aplicativo:

Insira um objeto CMFCMaskedEdit em sua classe de janela.
Chame o método CMFCMaskedEdit::EnableMask para especificar a máscara.
Chame o método CMFCMaskedEdit::SetValidChars para especificar a lista de caracteres válidos.
Chame o método CMFCMaskedEdit::SetWindowText para especificar o texto padrão para o controle de edição mascarada.
Chame o método CMFCMaskedEdit::GetWindowText para recuperar o texto validado.

Se você não chamar um ou mais métodos para inicializar a máscara, os caracteres válidos e o texto padrão, o controle de edição mascarada se comportará da mesma forma que o controle de edição padrão se comporta.

Exemplo

O exemplo a seguir demonstra como configurar uma máscara (por exemplo, um número de telefone) usando o método EnableMask para criar a máscara para o controle de edição mascarada, o método SetValidChars para especificar uma cadeia de caracteres válidos que o usuário pode inserir e o método SetWindowText para exibir um prompt no controle de edição mascarada. Este exemplo faz parte da amostra de Novos Controles.

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);
}

Hierarquia de herança

Requisitos

Cabeçalho: afxmaskededit.h

CMFCMaskedEdit::DisableMask

Desabilita a validação da entrada do usuário.

void DisableMask();

Comentários

Se a validação de entrada do usuário estiver desabilitada, o controle de edição mascarada se comportará como o controle de edição padrão.

CMFCMaskedEdit::EnableGetMaskedCharsOnly

Especifica se o método GetWindowText recupera apenas caracteres mascarados.

void EnableGetMaskedCharsOnly(BOOL bEnable=TRUE);

Parâmetros

bEnable
[in] TRUE para especificar que o método CMFCMaskedEdit::GetWindowText recupere apenas caracteres mascarados; FALSE para especificar que o método recupere todo o texto. O valor padrão é TRUE.

Comentários

Use esse método para habilitar a recuperação de caracteres mascarados. Em seguida, crie um controle de edição mascarada que corresponda ao número de telefone, como (425) 555-0187. Se você chamar o método GetWindowText, ele retornará "4255550187". Se você desabilitar a recuperação de caracteres mascarados, o método GetWindowText retornará o texto exibido no controle de edição, por exemplo "(425) 555-0187".

CMFCMaskedEdit::EnableMask

Inicializa o controle de edição mascarada.

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

Parâmetros

lpszMask
[in] Uma cadeia de caracteres de máscara que especifica o tipo de caractere que pode aparecer em cada posição na entrada do usuário. O comprimento das cadeias de caracteres de parâmetro lpszInputTemplate e lpszMask deve ser o mesmo. Consulte a seção Comentários para obter mais detalhes sobre caracteres de máscara.

lpszInputTemplate
[in] Uma cadeia de caracteres de modelo de máscara que especifica os caracteres literais que pode aparecer em cada posição na entrada do usuário. Use o caractere ('_') sublinhado como um espaço reservado para caracteres. O comprimento das cadeias de caracteres de parâmetro lpszInputTemplate e lpszMask deve ser o mesmo.

chMaskInputTemplate
[in] Um caractere padrão que a estrutura substitui por cada caractere inválido na entrada do usuário. O valor padrão desse parâmetro é sublinhado ('_').

lpszValid
[in] Uma cadeia de caracteres que contém um conjunto de caracteres válidos. NULL indica que todos os caracteres são válidos. O valor padrão desse parâmetro é NULL.

Comentários

Use esse método para criar a máscara para o controle de edição mascarada. Derive uma classe da classe CMFCMaskedEdit e substitua o método CMFCMaskedEdit::IsMaskedChar para usar seu próprio código para processamento de máscara personalizado.

A tabela a seguir lista os caracteres de máscara padrão:

Caractere de máscara	Definição
D	Dígido.
d	Dígito ou espaço.
+	Mais ('+'), menos ('-') ou espaço.
C	Caractere alfabético.
c	Caractere alfabético ou espaço.
Um	Caractere alfanumérico.
um	Caractere alfanumérico ou espaço.
*	Um caractere imprimível.

CMFCMaskedEdit::EnableSelectByGroup

Especifica se o controle de edição mascarada permite que o usuário selecione entrada de grupos específicos ou todas as entradas.

void EnableSelectByGroup(BOOL bEnable=TRUE);

Parâmetros

bEnable
[in] TRUE para selecionar apenas grupos; FALSE para selecionar o texto inteiro. O valor padrão é TRUE.

Comentários

Use essa função para especificar se o controle de edição mascarada permite que um usuário selecione por grupo ou todo o texto.

Por padrão, a seleção por grupo está habilitada. Nesse caso, o usuário pode selecionar apenas grupos contínuos de caracteres válidos.

Por exemplo, você pode usar o seguinte controle de edição mascarada para validar um número de telefone:

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

Se a seleção por grupo estiver habilitada, o usuário poderá recuperar apenas os grupos de cadeias de caracteres "425", "555" ou "0187". Se a seleção de grupo estiver desabilitada, o usuário poderá recuperar todo o texto do número de telefone: "(425) 555-0187".

CMFCMaskedEdit::EnableSetMaskedCharsOnly

Especifica se o texto é validado somente em caracteres mascarados ou em toda a máscara.

void EnableSetMaskedCharsOnly(BOOL bEnable=TRUE);

Parâmetros

bEnable
[in] TRUE para validar a entrada do usuário somente em caracteres mascarados; FALSE para validar em relação a toda a máscara. O valor padrão é TRUE.

CMFCMaskedEdit::GetWindowText

Recupera o texto validado do controle de edição mascarada.

int GetWindowText(
    LPTSTR lpszStringBuf,
    int nMaxCount) const;

void GetWindowText(CString& rstrString) const;

Parâmetros

lpszStringBuf
[out] Um ponteiro para um buffer que recebe o texto do controle de edição.

nMaxCount
[in] O número máximo de caracteres a serem recebidos.

rstrString
[out] Uma referência ao objeto de cadeia de caracteres que recebe o texto do controle de edição.

Valor de retorno

A sobrecarga do primeiro método retorna o número de bytes da cadeia de caracteres copiada para o buffer de parâmetro lpszStringBuf; 0 se o controle de edição mascarada não tiver texto.

Comentários

Esse método copia o texto do controle de edição mascarada para o buffer lpszStringBuf ou a cadeia de caracteres rstrString.

Esse método redefine CWnd::GetWindowText.

CMFCMaskedEdit::IsMaskedChar

Chamado pela estrutura para validar o caractere especificado em relação ao caractere de máscara correspondente.

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

Parâmetros

chChar
[in] O caractere a ser validado.

chMaskChar
[in] O caractere correspondente da cadeia de caracteres de máscara.

Valor de retorno

TRUE se o parâmetro chChar for o tipo de caractere permitido pelo parâmetro chMaskChar; caso contrário, FALSE.

Comentários

Substitua esse método para validar caracteres de entrada por conta própria. Para obter mais informações sobre caracteres de máscara, consulte o método CMFCMaskedEdit::EnableMask.

CMFCMaskedEdit::SetValidChars

Especifica uma cadeia de caracteres válida que o usuário pode inserir.

void SetValidChars(LPCTSTR lpszValid=NULL);

Parâmetros

lpszValid
[in] Uma cadeia de caracteres que contém o conjunto de caracteres de entrada válidos. NULL significa que todos os caracteres são válidos. O valor padrão desse parâmetro é NULL.

Comentários

Use este método para definir uma lista de caracteres válidos. Se um caractere de entrada não estiver nessa lista, o controle de edição mascarada não o aceitará.

O exemplo de código a seguir aceita apenas números hexadecimais.

//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

Exibe um prompt no controle de edição mascarada.

void SetWindowText(LPCTSTR lpszString);

Parâmetros

lpszString
[in] Aponta para uma cadeia de caracteres terminada em null que será usada como prompt.

Comentários

Esse método define o texto de controle.

Esse método redefine CWnd::GetWindowText.

Confira também

Gráfico da hierarquia
Classes
Classe CEdit

Compartilhar via

Classe CMFCMaskedEdit

Sintaxe

Membros

Construtores públicos

Métodos públicos

Métodos protegidos

Comentários

Exemplo

Hierarquia de herança

Requisitos

CMFCMaskedEdit::DisableMask

Comentários

CMFCMaskedEdit::EnableGetMaskedCharsOnly

Parâmetros

Comentários

CMFCMaskedEdit::EnableMask

Parâmetros

Comentários

CMFCMaskedEdit::EnableSelectByGroup

Parâmetros

Comentários

CMFCMaskedEdit::EnableSetMaskedCharsOnly

Parâmetros

CMFCMaskedEdit::GetWindowText

Parâmetros

Valor de retorno

Comentários

CMFCMaskedEdit::IsMaskedChar

Parâmetros

Valor de retorno

Comentários

CMFCMaskedEdit::SetValidChars

Parâmetros

Comentários

CMFCMaskedEdit::SetWindowText

Parâmetros

Comentários

Confira também

Comentários

Recursos adicionais