Esta documentación está archivada y no tiene mantenimiento.

MaskedTextBox (Clase)

Utiliza una máscara para distinguir entre la entrada de usuario correcta e incorrecta.

Espacio de nombres: System.Windows.Forms
Ensamblado: System.Windows.Forms (en system.windows.forms.dll)

[ClassInterfaceAttribute(ClassInterfaceType.AutoDispatch)] 
[ComVisibleAttribute(true)] 
public class MaskedTextBox : TextBoxBase
/** @attribute ClassInterfaceAttribute(ClassInterfaceType.AutoDispatch) */ 
/** @attribute ComVisibleAttribute(true) */ 
public class MaskedTextBox extends TextBoxBase
ClassInterfaceAttribute(ClassInterfaceType.AutoDispatch) 
ComVisibleAttribute(true) 
public class MaskedTextBox extends TextBoxBase
No aplicable.

La clase MaskedTextBox es un control TextBox mejorado que admite una sintaxis declarativa para aceptar o rechazar los datos proporcionados por el usuario. Con la propiedad Mask puede especificar la entrada siguiente sin escribir ninguna lógica de validación personalizada en su aplicación:

  • Caracteres de entrada necesarios.

  • Caracteres de entrada opcionales.

  • El tipo de entrada esperada en una posición determinada de la máscara; por ejemplo, un dígito, o un carácter alfabético o alfanumérico.

  • Los literales de máscara, o caracteres que deben aparecer directamente en el MaskedTextBox; por ejemplo, los guiones (-) en un número de teléfono o el símbolo de moneda en un precio.

  • Procesamiento especial para los caracteres de entrada; por ejemplo, para convertir caracteres alfabéticos a mayúsculas.

Cuando se muestra un control MaskedTextBox en tiempo de ejecución, representa la máscara como una serie de caracteres de entrada y literales de cadena opcionales. Cada posición modificable de la máscara, que representa una entrada necesaria u opcional, se muestra con un único carácter de entrada. Por ejemplo, el signo de número (#) suele utilizarse como un marcador de posición para una entrada de caracteres numéricos. Se puede utilizar la propiedad PromptChar para especificar un carácter de entrada personalizado. La propiedad HidePromptOnLeave determina si el usuario ve los caracteres de entrada cuando el control pierde el foco de entrada.

A medida que el usuario escribe datos en el cuadro de texto enmascarado, los caracteres de entrada válidos reemplazan sus respectivos caracteres de entrada de modo secuencial. Si el usuario escribe un carácter de entrada no válido, no se realiza ningún reemplazo, sino que se emite un bip si la propiedad BeepOnError se establece en true y se produce el evento MaskInputRejected. Puede proporcionar su propia lógica de error personalizada controlando este evento.

Cuando el punto de inserción actual está en un literal de cadena, el usuario tiene varias opciones:

  • Si se escribe un carácter distinto del carácter de entrada, se omitirá automáticamente el literal y el carácter de entrada se aplicará a la siguiente posición modificable, representada por el siguiente carácter de entrada.

  • Si se escribe el carácter de entrada y la propiedad AllowPromptAsInput es true, la entrada sobrescribirá el carácter de entrada y el punto de inserción se desplazará a la siguiente posición de la máscara.

  • Como siempre, las teclas de dirección pueden utilizarse para desplazarse a una posición anterior o siguiente.

Puede utilizar la propiedad MaskFull para comprobar si el usuario ha escrito o no todos los datos de entrada necesarios. La propiedad Text siempre recuperará la entrada del usuario con el formato especificado por la máscara y la propiedad TextMaskFormat.

El control MaskedTextBox cede realmente todo el procesamiento de la máscara a la clase System.ComponentModel.MaskedTextProvider especificada por la propiedad MaskedTextProvider. Este proveedor estándar admite todos los caracteres Unicode salvo los suplentes y los caracteres combinados verticalmente; sin embargo, se puede utilizar la propiedad AsciiOnly para restringir la entrada a los conjuntos de caracteres a-z, A-Z y 0-9.

Las máscaras no garantizan necesariamente que la entrada de un usuario representará un valor válido para un tipo determinado; por ejemplo, se puede escribir -9 como una edad en años. Puede comprobar que la entrada de un usuario representa un valor válido asignando una instancia del tipo de ese valor a la propiedad ValidatingType. Puede detectar si el usuario quita el foco de MaskedTextBox cuando contiene un valor no válido supervisando el evento TypeValidationCompleted. Si la validación de tipo tiene éxito, el objeto que representa el valor estará disponible a través de la propiedad ReturnValue del parámetro TypeValidationEventArgs.

Como ocurre con el control TextBox, varios métodos abreviados de teclado comunes no funcionan con MaskedTextBox. En particular, CTRL-R (justificar el texto a la derecha), CTRL-L (justificar el texto a la izquierda) y CTRL-L (centrar el texto) no surten ningún efecto.

Compatibilidad con Visual Basic 6.0

MaskedTextBox fue diseñado para conservar la mayor parte de la funcionalidad del control Masked Edit en Visual Basic 6.0. En la tabla siguiente se muestran las propiedades comunes del control Masked Edit y se proporcionan sus equivalentes en MaskedTextBox.

Propiedad del control Masked Edit (Visual Basic 6.0)

Propiedad equivalente de MaskedTextBox (.NET Framework)

Propiedad AllowPrompt

AllowPromptAsInput

Propiedad AutoTab

Ninguna

Propiedad ClipMode

CutCopyMaskFormat

Propiedad ClipText

Text (cuando TextMaskFormat se establece en ExcludePromptAndLiterals).

Propiedad Format

Ninguna

Propiedad FormattedText

Text (cuando TextMaskFormat se establece en IncludePromptAndLiterals).

Propiedad Mask

Mask

Propiedad PromptChar

PromptChar

Propiedad PromptInclude

ResetOnPrompt

Evento ValidationError.

MaskInputRejected

Nota de precauciónPrecaución:

El control MaskedTextBox no permite la configuración de múltiples líneas ni funcionalidad para deshacer. Sin embargo, aunque los miembros asociados a estas características se han conservado por compatibilidad con la clase base TextBoxBase, sus implementaciones no realizan ninguna acción.

En el ejemplo de código siguiente se inicializa el MaskedTextBox para aceptar una fecha, y se utilizan los eventos MaskInputRejected y TypeValidationCompleted para avisar al usuario de que la entrada no es válida.

private void Form1_Load(object sender, EventArgs e)
{
    maskedTextBox1.Mask = "00/00/0000";

    maskedTextBox1.MaskInputRejected += new MaskInputRejectedEventHandler(maskedTextBox1_MaskInputRejected);
    maskedTextBox1.KeyDown += new KeyEventHandler(maskedTextBox1_KeyDown);
}

void maskedTextBox1_MaskInputRejected(object sender, MaskInputRejectedEventArgs e)
{
    if (maskedTextBox1.MaskFull)
    {
        toolTip1.ToolTipTitle = "Input Rejected - Too Much Data";
        toolTip1.Show("You cannot enter any more data into the date field. Delete some characters in order to insert more data.", maskedTextBox1, 0, -20, 5000);
    }
    else if (e.Position == maskedTextBox1.Mask.Length)
    {
        toolTip1.ToolTipTitle = "Input Rejected - End of Field";
        toolTip1.Show("You cannot add extra characters to the end of this date field.", maskedTextBox1, 0, -20, 5000);
    }
    else
    {
        toolTip1.ToolTipTitle = "Input Rejected";
        toolTip1.Show("You can only add numeric characters (0-9) into this date field.", maskedTextBox1, 0, -20, 5000);
    }
}

void maskedTextBox1_KeyDown(object sender, KeyEventArgs e)
{
    // The balloon tip is visible for five seconds; if the user types any data before it disappears, collapse it ourselves.
    toolTip1.Hide(maskedTextBox1);
}

System.Object
   System.MarshalByRefObject
     System.ComponentModel.Component
       System.Windows.Forms.Control
         System.Windows.Forms.TextBoxBase
          System.Windows.Forms.MaskedTextBox

Los miembros estáticos públicos (Shared en Visual Basic) de este tipo son seguros para la ejecución de subprocesos. No se garantiza que los miembros de instancias sean seguros para la ejecución de subprocesos.

Windows 98, Windows 2000 Service Pack 4, Windows CE, Windows Millennium, Windows Mobile para Pocket PC, Windows Mobile para Smartphone, Windows Server 2003, Windows XP Media Center, Windows XP Professional x64, Windows XP SP2, Windows XP Starter

Microsoft .NET Framework 3.0 es compatible con Windows Vista, Microsoft Windows XP SP2 y Windows Server 2003 SP1.

.NET Framework

Compatible con: 3.0, 2.0
Mostrar: