MaskedNumberField

Le MaskedNumberField est un champ de texte conçu pour formater les saisies numériques de manière cohérente, en fonction d'un masque défini. Il est utile pour les formulaires financiers, les champs de prix, ou toute entrée où la précision et la lisibilité sont importantes.

Ce composant peut être instancié avec ou sans paramètres. Il prend en charge le formatage des nombres, la localisation des caractères décimaux/de groupement, et des contraintes de valeur optionnelles comme des minimums ou maximums. Il permet également de définir une valeur initiale, une étiquette, un espace réservé et un écouteur d'événements pour réagir aux changements de valeur.

L'exemple ci-dessous présente un Calculateur de pourboire qui utilise MaskedNumberField pour une saisie numérique intuitive. Un champ est configuré pour accepter un montant de facture formaté, tandis que l'autre capture un pourcentage de pourboire sous forme de nombre entier.

Règles de masque

Le MaskedNumberField utilise une chaîne de masque pour contrôler comment la saisie numérique est formatée et affichée. Chaque caractère du masque définit un comportement de formatage spécifique, permettant un contrôle précis sur l'apparence des nombres.

Application de masques par programmation

Pour formater les nombres avec la même syntaxe de masque en dehors d'un champ, par exemple lors du rendu de données dans un Table, utilisez la classe utilitaire MaskDecorator.

Caractères de masque

Caractère	Description
`0`	Toujours remplacé par un chiffre (0–9).
`#`	Supprime les zéros non significatifs. Remplace par le caractère de remplissage à gauche de la virgule. Pour les chiffres suivants, remplacé par un espace ou un zéro. Sinon, remplacé par un chiffre.
`,`	Utilisé comme séparateur de groupement (ex. milliers). Remplacé par le caractère de remplissage si aucun chiffre ne le précède. Sinon, affiché comme une virgule.
`-`	Affiche un signe moins (`-`) si le nombre est négatif. Remplacé par le caractère de remplissage si positif.
`+`	Affiche `+` pour les nombres positifs ou `-` pour les nombres négatifs.
`$`	Résulte toujours en un signe dollar.
`(`	Insère une parenthèse gauche `(` pour les valeurs négatives. Remplacé par le caractère de remplissage si positif.
`)`	Insère une parenthèse droite `)` pour les valeurs négatives. Remplacé par le caractère de remplissage si positif.
`CR`	Affiche `CR` pour les nombres négatifs. Affiche deux espaces si le nombre est positif.
`DR`	Affiche `CR` pour les nombres négatifs. Affiche `DR` pour les nombres positifs.
`*`	Insère un astérisque `*`.
`.`	Marque le point décimal. Si aucun chiffre n'apparaît dans la sortie, remplacé par le caractère de remplissage. Après le décimal, les caractères de remplissage sont traités comme des espaces.
`B`	Devient toujours un espace. Tout autre caractère littéral est affiché tel quel.

Certains des caractères ci-dessus peuvent apparaître plus d'une fois dans le masque pour le formatage. Ceci inclut -, +, $, et (. Si l'un de ces caractères est présent dans le masque, le premier rencontré sera déplacé à la dernière position où un # ou une , a été remplacé par le caractère de remplissage. Si aucune position de ce type n'existe, le caractère double reste à sa place.

Pas d'arrondi automatique

Un masque dans un champ ne fait PAS d'arrondi. Par exemple, lorsque vous placez une valeur telle que 12.34567 dans un champ masqué avec ###0.00, vous obtiendrez 12.34.

Séparateurs de groupe et décimaux

Le MaskedNumberField prend en charge la personnalisation des caractères de groupement et décimaux, facilitant ainsi l'adaptation du formatage des nombres aux différentes locales ou conventions commerciales.

Le séparateur de groupe est utilisé pour séparer visuellement les milliers (ex. 1,000,000).
Le séparateur décimal indique la partie fractionnaire d'un nombre (ex. 123.45).

Cela est utile dans les applications internationales où différentes régions utilisent différents caractères (ex. . vs ,).

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

Comportement par défaut

Par défaut, MaskedNumberField applique les séparateurs de groupe et décimaux en fonction de la locale actuelle de l'application. Vous pouvez les remplacer à tout moment en utilisant les setters fournis.

Négatif

Le MaskedNumberField prend en charge une option pour contrôler si les nombres négatifs sont autorisés.

Par défaut, des valeurs négatives comme -123.45 sont acceptées. Pour empêcher cela, utilisez setNegateable(false) pour restreindre l'entrée aux valeurs positives uniquement.

Cela est utile dans les scénarios commerciaux où des valeurs comme les quantités, les totaux ou les pourcentages doivent toujours être non négatifs.

field.setNegateable(false);

Lorsque negatable est défini sur false, le champ bloque toute tentative d'entrer un signe moins ou d'autres valeurs négatives.

Valeurs min et max

Le MaskedNumberField prend en charge la définition de limites numériques à l'aide de setMin() et setMax(). Ces contraintes aident à garantir que les saisies des utilisateurs restent dans une plage valide et attendue.

Valeur minimale Utilisez setMin() pour définir le nombre le plus bas acceptable :
```
field.setMin(10.0); // Valeur minimale : 10
```
Si l'utilisateur saisit un nombre en dessous de ce seuil, il sera considéré comme invalide.
Valeur maximale Utilisez setMax() pour définir le nombre le plus élevé acceptable :
```
field.setMax(100.0); // Valeur maximale : 100
```
Les valeurs au-dessus de cette limite seront marquées comme invalides.

Restauration de la valeur

Le MaskedNumberField prend en charge une fonction de restauration qui réinitialise la valeur du champ à un état prédéfini. Cela peut être utile lorsque les utilisateurs ont besoin d'annuler des modifications, de revenir sur des modifications accidentelles ou de retourner à une valeur par défaut connue.

Pour restaurer une valeur spécifique, définissez-la en utilisant setRestoreValue(). Lorsque cela est nécessaire, le champ peut être réinitialisé par programme à l'aide de restoreValue().

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

Façons de restaurer la valeur

Par programme en utilisant restoreValue()
Via le clavier, en appuyant sur ESC (c'est la touche de restauration par défaut, sauf si elle est remplacée)

Si aucune valeur de restauration n'est définie, à la fois restoreValue() et ESC définissent la valeur du champ sur null.