MaskedNumberField

El MaskedNumberField es un campo de texto diseñado para la entrada numérica estructurada. Asegura que los números se formateen de manera consistente según una máscara definida, lo que lo hace especialmente útil para formularios financieros, campos de precios o cualquier entrada donde la precisión y legibilidad sean importantes.

Este componente admite el formateo de números, la localización de caracteres decimales/grupales, y restricciones de valor opcionales como mínimos o máximos.

Básicos

El MaskedNumberField se puede instanciar con o sin parámetros. Admite establecer un valor inicial, una etiqueta, un texto de marcador y un oyente de eventos para reaccionar a cambios de valor.

Esta demostración muestra un Calculador de Propinas que utiliza MaskedNumberField para una entrada numérica intuitiva. Un campo está configurado para aceptar un monto de cuenta formateado, mientras que el otro captura un porcentaje de propina en número entero. Ambos campos aplican máscaras numéricas para asegurar un formato consistente y predecible.

Mostrar Código

MaskedNumberFieldView.java

Reglas de la máscara

El MaskedNumberField utiliza una cadena de máscara para controlar cómo se formatea y muestra la entrada numérica. Cada carácter en la máscara define un comportamiento de formateo específico, permitiendo un control preciso sobre cómo aparecen los números.

Aplicando máscaras programáticamente

Para formatear números con la misma sintaxis de máscara fuera de un campo, por ejemplo al renderizar datos en una Table, utiliza la clase de utilidad MaskDecorator.

Caracteres de la máscara

Caracter	Descripción
`0`	Siempre reemplazado por un dígito (0–9).
`#`	Suprime ceros a la izquierda. Reemplazado por el carácter de relleno a la izquierda del punto decimal. Para dígitos finales, reemplazado por un espacio o cero. De lo contrario, reemplazado por un dígito.
`,`	Utilizado como separador de grupos (p.ej. miles). Reemplazado por el carácter de relleno si no hay dígitos que lo precedan. De lo contrario, se muestra como una coma.
`-`	Muestra un signo menos (`-`) si el número es negativo. Reemplazado por el carácter de relleno si es positivo.
`+`	Muestra `+` para números positivos o `-` para números negativos.
`$`	Siempre resulta en un signo de dólar.
`(`	Inserta un paréntesis izquierdo `(` para valores negativos. Reemplazado por el carácter de relleno si es positivo.
`)`	Inserta un paréntesis derecho `)` para valores negativos. Reemplazado por el carácter de relleno si es positivo.
`CR`	Muestra `CR` para números negativos. Muestra dos espacios si el número es positivo.
`DR`	Muestra `CR` para números negativos. Muestra `DR` para números positivos.
`*`	Inserta un asterisco `*`.
`.`	Marca el punto decimal. Si no aparecen dígitos en la salida, se reemplaza por el carácter de relleno. Después del decimal, los caracteres de relleno se tratan como espacios.
`B`	Siempre se convierte en un espacio. Cualquier otro carácter literal se muestra tal cual.

Algunos de los caracteres anteriores pueden aparecer más de una vez en la máscara para formatear. Estos incluyen -, +, $, y (. Si alguno de estos caracteres está presente en la máscara, el primero que se encuentre se moverá a la última posición donde un # o , fue reemplazado por el carácter de relleno. Si no existe tal posición, el carácter doble se deja donde está.

Sin Redondeo Automático

Una máscara dentro de un campo no REDONDEA. Por ejemplo, al colocar un valor como 12.34567 en un campo que está enmascarado con ###0.00, obtendrás 12.34.

Separadores grupales y decimales

El MaskedNumberField admite la personalización de los caracteres de agrupación y decimal, facilitando la adaptación del formateo numérico a diferentes localidades o convenciones comerciales.

El separador de grupos se usa para separar visualmente los miles (p.ej. 1,000,000).
El separador decimal indica la parte fraccionaria de un número (p.ej. 123.45).

Esto es útil en aplicaciones internacionales donde diferentes regiones utilizan diferentes caracteres (p.ej. . vs ,).

field.setGroupCharacter(".");   // p.ej. 1.000.000
field.setDecimalCharacter(","); // p.ej. 123,45

Comportamiento por Defecto

Por defecto, MaskedNumberField aplica separadores grupales y decimales basados en la localidad actual de la aplicación. Puedes sobreescribirlos en cualquier momento utilizando los métodos setters proporcionados.

Negable

El MaskedNumberField admite una opción para controlar si se permiten números negativos.

Por defecto, se permiten valores negativos como -123.45. Para evitar esto, usa setNegateable(false) para restringir la entrada a valores positivos solamente.

Esto es útil en escenarios comerciales donde valores como cantidades, totales o porcentajes deben ser siempre no negativos.

field.setNegateable(false);

Cuando negatable se establece en false, el campo bloquea cualquier intento de ingresar un signo menos o de otra manera introducir valores negativos.

Mostrar Código

MaskedNumNegatableView.java

Valores Mínimos y Máximos

El MaskedNumberField admite establecer límites numéricos utilizando setMin() y setMax(). Estas restricciones ayudan a garantizar que la entrada del usuario se mantenga dentro de un rango válido y esperado.

Valor Mínimo Usa setMin() para definir el número más bajo aceptable:
```
field.setMin(10.0); // Valor mínimo: 10
```
Si el usuario ingresa un número por debajo de este umbral, se considerará inválido.
Valor Máximo Usa setMax() para definir el número más alto aceptable:
```
field.setMax(100.0); // Valor máximo: 100
```
Los valores superiores a este límite se marcarán como inválidos.

Restaurando el valor

El MaskedNumberField admite una función de restauración que restablece el valor del campo a un estado predefinido. Esto puede ser útil cuando los usuarios necesitan deshacer cambios, revertir ediciones accidentales o volver a un valor predeterminado conocido.

Para habilitar este comportamiento, define el valor objetivo utilizando setRestoreValue(). Cuando sea necesario, el campo se puede restablecer programáticamente utilizando restoreValue().

numberField.setRestoreValue(1500.00);
numberField.restoreValue();

Formas de restaurar el valor

Programáticamente utilizando restoreValue()
A través del teclado, presionando ESC (esta es la tecla de restauración predeterminada a menos que se anule)

El valor de restauración debe establecerse explícitamente. Si no se define, la función no revertirá el campo.

Mostrar Código

MaskedNumRestoreView.java