VB .NET - Trabalhando com o controle MaskEditBox

VB .NET - Trabalhando como controle MaskedTextBox

A entrada de dados em um formulário Windows talvez seja a tarefa mais corriqueira que existe, afinal vivemos preenchendo estes benditos formulários a vida inteira.

Hoje eu vou falar sobre o controle MaskedTextBox que é um controle TextBox que utiliza uma máscara que pode ser customizada para avaliar a entrada do usuário formatando-a e validando-a.

A propriedade Mask do controle recebe uma string que define a máscara de entrada para o controle e usando a esta propriedade você pode especificar critérios sem escrever qualquer lógica de validação personalizada em seu aplicativo tais como:

Definir Caracteres de entrada necessárias ;
Definir Caracteres de entrada opcionais;
Definir o tipo de entrada esperado em uma posição determinada na máscara; por exemplo, um dígito ou um caractere alfabético ou alfanumérico;
Usar Literais de máscara ou caracteres que devem ser exibido diretamente no MaskedTextBox; Ex: hifens (-) em um número de telefone ou o símbolo da moeda em um preço;
Definir caracteres Especiais de processamento de caracteres de entrada; por exemplo, para converter caracteres alfabéticos em maiúsculas;

Esta propriedade permite que você defina uma string que representa o formato exigido para a seqüência de entrada colocado no MaskedTextBox. O valor padrão é uma seqüência vazia, que permite que qualquer entrada.

Quando um controle MaskedTextBox é exibido em tempo de execução, ele representa a máscara como uma série de caracteres de entrada e caracteres literais opcionais. Cada posição de máscara editáveis, que representa uma entrada obrigatória ou opcional, é mostrada com um único caractere de aviso. Por exemplo, o sinal numérico (#) é geralmente usado como um espaço reservado para uma entrada de caractere numérico. Você pode usar a propriedade para especificar um caractere de prompt personalizado.

Se o usuário informar um caractere incorreto o controle irá emitir um aviso sonoro se a propriedade BeepOnError estiver definida como True e o evento MaskInputRejected será disparado de forma que você poderá personalizar o tratamento da entrada incorreta.

Você pode usar a propriedade MaskFull para verificar se o usuário inseriu todas a entrada necessária;

A propriedade Text sempre irá recuperar a entrada do usuário formatada de acordo com a máscara e a propriedade TextMaskFormat.

Você pode definir uma máscara para o controle selecionando o controle e clicando no link Set Mask...:

Será apresentada uma relação de definições de máscaras prontos mas você também pode definir uma máscara a seu critério:

A seguir temos as propriedades mais importantes deste controle:

AllowPromptAsInput - Indica se um PromptChar pode ser considerado um dado válido pelo usuário;
AsciiOnly - Indica se o controle e MaskedTextBox aceita caracteres além do conjunto de caracteres ASCII;
BeepOnError - Indica se o controle dispara um beep para cada entrada inválida;
CutCopyMaskFormat - Determina se literais e caracteres de entrada serão copiados para o clipboard;
HidePromptOnLeave - Indica se o caractere informado na máscara de entrada serão ocultos quando o o controle perde o foco;
InsertKeyMode - Especifica o modo de inserção de texto do controle;
Mask - Especifica a máscara de entrada a ser usada;
PromptChar - Especifica o caractere usado para representar a ausência de entrada do usuário no controle;
RejectInputOnFirstFailure - Indica se a análise da entrada do usuário será interrompida depois do primeiro caractere inválido;
ResetOnPrompt - Determina como uma entrada de caractere que equivale na entrada será tratado;
ResetOnSpace - Determina como uma entrada de espaço será tratada;
SkipLiterals - Indica se o usuário pode reentrar valores literais;
TextMaskFormat - Determina se literais e caracteres de entrada serão incluídos na string formatada;

A máscara é composta de um ou mais dos elementos de mascaramento conforme a tabela abaixo. (O MaskedTextProvider associado ao MaskedTextBox fornece o mecanismo de análise para a Máscara.)

`0`	Dígito requerido. Este elemento aceitará qualquer dígito entre 0 e 9.
`9`	Dígito ou espaço, opcional.
`#`	Dígito ou espaço, opcional. Se a posição estiver em branco na máscara, ela será renderizada como um espaço na propriedade Text. Os sinais Mais (+) e menos (-) são permitidos
`L`	Letra, requerido. Restringe a entrada para ASCII letras a-z and A-Z. Este elemento mask é equivalente a [a-zA-Z] nas expressões regulares
`?`	Letra, opcional. Restringe a entrada para ASCII letras a-z and A-Z. Este elemento mask é equivalente a [a-zA-Z]? nas expressões regulares
`&`	Caractere, requerido. Se a propriedade `AsciiOnly` for definida como true, este elemento comporta-se como o elemento L
`C`	Caractere, opcional. Qualquer caractere que não seja de controle. Se a propriedade `AsciiOnly` é definida como `true`, este elemento se comporta como "?";
`A`	Alfanumérico, opcional. Se a propriedade `AsciiOnly` for definida como true, os únicos caracteres que serão aceitos são as letras ASCII a-z e A-Z.
`a`	Alfanumérico, opcional. Se a propriedade `AsciiOnly` for definida como true, os únicos caracteres que serão aceitos são as letras ASCII a-z e A-Z.
`.`	Ponto Decimal. O caractere atual exibido usado será o símbolo decimal , como determinado pela propriedade `FormatProvider`;
`,`	Vírgula do milhar. O caractere atual exibido usado será o símbolo de milhar ,como determinado pela propriedade `FormatProvider`;
`:`	Separador de hora. O caractere atual exibido usado será o símbolo de hora , como determinado pela propriedade `FormatProvider`;
`/`	Separador de Data. O caractere atual exibido usado será o símbolo de data , como determinado pela propriedade `FormatProvider`;
`$`	Símbolo de Moeda. O caractere atual exibido será o símbolo da moeda , como determinado pela propriedade `FormatProvider`;
`<`	Sinal de Menor. Converte todos os caracteres para caixa baixa;
`>`	Sinal de maior. Converte todos os caracteres para caixa alta;
`\`	Limpa uma Caractere máscara, transformando-o em um literal. "\ \ " é a seqüência de escape para uma barra invertida

Embora tenha muitos recursos o controle MaskedTextBox não irá resolver todos os seus problemas de validação de entrada de usuário, pois ao mesmo tempo que ele torna mais fácil implementar alguns tipos de validações, sem realizar uma customização ele não garantirá que algumas validações comuns seja realizadas a contento.

A seguir irei mostrar alguns exemplos de utilização do controle MaskedTextBox onde usaremos botões de comandos para poder alterar a máscara ativa do controle para cada situação onde o controle irá tentar acomodar o conteúdo existente com a nova máscara alterada e se o conteúdo não for permitido o controle limpará o conteúdo.

Crie um novo projeto usando o Visual Basic 2010 Express Edition usando o template Windows Forms Application com o nome WF_MaskedTextBox;

A seguir inclua no formulário form1.vb um controle MaskedTextBox com name = mskTextBox, um controle Label e 4 Buttons conforme o leiaute abaixo:

A seguir inclua o código em cada evento Click do botão de comando conforme abaixo:

    Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click
        Me.mskTextBox.UseSystemPasswordChar = False
        Me.mskTextBox.Mask = "00:00"
        Me.lblmascaraAtiva.Text = Me.mskTextBox.Mask
        Me.mskTextBox.Focus()
    End Sub

    Private Sub Button2_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button2.Click
        Me.mskTextBox.UseSystemPasswordChar = False
        Me.mskTextBox.Mask = "99999-999"
        Me.lblmascaraAtiva.Text = Me.mskTextBox.Mask
        Me.mskTextBox.Focus()
    End Sub

    Private Sub Button3_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button3.Click
        Me.mskTextBox.UseSystemPasswordChar = False
        Me.mskTextBox.Mask = "$999,999.00"
        Me.lblmascaraAtiva.Text = Me.mskTextBox.Mask
        Me.mskTextBox.Focus()
    End Sub

    Private Sub Button4_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button4.Click
        Me.mskTextBox.UseSystemPasswordChar = False
        Me.mskTextBox.Mask = "00/00/0000"
        Me.lblmascaraAtiva.Text = Me.mskTextBox.Mask
        Me.mskTextBox.Focus()
    End Sub

    Private Sub Button5_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button5.Click
        mskTextBox.Mask = "00/00/0000"
        Me.lblmascaraAtiva.Text = Me.mskTextBox.Mask
        Me.mskTextBox.Focus()
    End Sub

Para realizar o tratamento de erros usamos para o botão 5 o evento MaskInputRejected conforme o código a seguir:

  Private Sub mskTextBox_MaskInputRejected_1(ByVal sender As System.Object, ByVal e As System.Windows.Forms.MaskInputRejectedEventArgs) Handles mskTextBox.MaskInputRejected
        If mskTextBox.MaskFull Then
            ToolTip1.ToolTipTitle = "Entrada rejeitada - Muitos dados"
            ToolTip1.Show("Você não pode informar mais dados neste campo.", mskTextBox, 0, -20, 5000)
        ElseIf ((e.Position = mskTextBox.Mask.Length)) Then
            ToolTip1.ToolTipTitle = "Entrada rejeitada - fim do campo"
            ToolTip1.Show("Você não pode informar caracteres extra a este campo.", mskTextBox, 0, -20, 5000)
        Else
            ToolTip1.ToolTipTitle = "Entrada rejeitada"
            ToolTip1.Show("Você só pode informar digitos numéricos entre (0-9) neste campo.", mskTextBox, 0, -20, 5000)
        End If
    End Sub

    Private Sub mskTextBox_KeyDown(ByVal sender As System.Object, ByVal e As System.Windows.Forms.KeyEventArgs) Handles mskTextBox.KeyDown
        ToolTip1.Hide(mskTextBox)
    End Sub

Simples , simples assim...

Pegue o projeto completo aqui: WF_MaskedTextBox.zip

Eu sei é apenas VB .NET, mas eu gosto...

Referências:

José Carlos Macoratti

Combobox : Usando o recurso AutoCompletar - Macoratti.net