MaskedNumberField

Het MaskedNumberField is een tekstinvoerveld ontworpen voor gestructureerde numerieke invoer. Het zorgt ervoor dat nummers consistent worden opgemaakt op basis van een gedefinieerde masker, wat het bijzonder nuttig maakt voor financiële formulieren, prijsvelden of elke invoer waar precisie en leesbaarheid van belang zijn.

Deze component ondersteunt nummeropmaak, lokalisatie van decimale/groeperingskarakters en optionele waarde beperkingen zoals minimums of maximums.

Basisprincipes

Het MaskedNumberField kan worden geïnstantieerd met of zonder parameters. Het ondersteunt het instellen van een initiële waarde, een label, een plaatsaanduiding en een gebeurtenisluisteraar om te reageren op waarde wijzigingen.

Deze demo toont een Foatokcalculator die MaskedNumberField gebruikt voor intuïtieve numerieke invoer. Één veld is geconfigureerd om een geformatteerd rekeningbedrag te accepteren, terwijl het andere een hele getal fooi percentage vastlegt. Beide velden passen numerieke maskers toe om consistente en voorspelbare opmaak te waarborgen.

Toon Code

MaskedNumberFieldView.java

Maskerregels

Het MaskedNumberField gebruikt een maskerstring om te controleren hoe numerieke invoer wordt opgemaakt en weergegeven. Elk karakter in het masker definieert een specifieke opmaakgedrag, waardoor nauwkeurige controle over hoe cijfers verschijnen mogelijk is.

Toepassen van maskers programmatisch

Om cijfers met dezelfde masker syntax buiten een veld te formatteren, bijvoorbeeld bij het weergeven van gegevens in een Table, gebruik de MaskDecorator utilityklasse.

Maskerkarakters

Karakter	Beschrijving
`0`	Altijd vervangen door een cijfer (0–9).
`#`	Onderdrukt leidende nullen. Vervangen door het vulteken aan de linkerkant van het decimale punt. Voor achterliggende cijfers vervangen door een spatie of nul. Anders, vervangen door een cijfer.
`,`	Gebruik als een groeperingsscheidingsteken (bijv. duizenden). Vervangen door het vulteken als er geen cijfers aan voorafgaan. Anders, als een komma weergegeven.
`-`	Weergeven een minteken (`-`) als het getal negatief is. Vervangen door het vulteken als het positief is.
`+`	Weergeven `+` voor positieve of `-` voor negatieve getallen.
`$`	Geeft altijd een dollar teken.
`(`	Voegt een linkse haakje `(` in voor negatieve waarden. Vervangen door het vulteken als het positief is.
`)`	Voegt een rechtse haakje `)` in voor negatieve waarden. Vervangen door het vulteken als het positief is.
`CR`	Weergeven `CR` voor negatieve getallen. Weergeven twee spaties als het getal positief is.
`DR`	Weergeven `CR` voor negatieve getallen. Weergeven `DR` voor positieve getallen.
`*`	Voegt een asterisk `*` in.
`.`	Merkt het decimale punt aan. Als er geen cijfers in de uitvoer verschijnen, vervangen door het vulteken. Na het decimale punt worden vultekens als spaties behandeld.
`B`	Wordt altijd een spatie. Elk ander letterlijk karakter wordt weergegeven zoals het is.

Sommige van de bovenstaande karakters kunnen meer dan eens in het masker voorkomen voor opmaak. Dit zijn -, +, $, en (. Als een van deze karakters in het masker aanwezig is, wordt de eerste die wordt aangetroffen verplaatst naar de laatste positie waar een # of , door het vulteken is vervangen. Als er geen dergelijke positie bestaat, blijft het dubbele karakter waar het is.

Geen automatische afronding

Een masker binnen een veld rondt NIET af. Bijvoorbeeld, wanneer een waarde zoals 12.34567 in een veld wordt geplaatst dat is gemaskeerd met ###0.00, krijg je 12.34.

Groep en decimale scheidingstekens

Het MaskedNumberField ondersteunt aanpassing van groeps- en decimale karakters, waardoor het eenvoudig is om nummeropmaak aan te passen aan verschillende lokale of zakelijke conventies.

De groepscheidingsteken wordt gebruikt om duizenden visueel te scheiden (bijv. 1.000.000).
De decimale scheidingsteken geeft het fractionele deel van een getal aan (bijv. 123.45).

Dit is nuttig in internationale toepassingen waar verschillende gebieden verschillende karakters gebruiken (bijv. . vs ,).

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

Standaardgedrag

Standaard past MaskedNumberField groeps- en decimale scheidingstekens toe op basis van de huidige locale van de app. Je kunt ze op elk moment overschrijven met de gegeven setters.

Negatief

Het MaskedNumberField ondersteunt een optie om te controleren of negatieve getallen zijn toegestaan.

Standaard zijn negatieve waarden zoals -123.45 toegestaan. Om dit te voorkomen, gebruik setNegateable(false) om invoer te beperken tot alleen positieve waarden.

Dit is nuttig in zakelijke scenario's waar waarden zoals hoeveelheden, totalen of percentages altijd niet-negatief moeten zijn.

field.setNegateable(false);

Wanneer negatable is ingesteld op false, blokkeert het veld elke poging om een minteken in te voeren of op andere wijze negatieve waarden in te voeren.

Toon Code

MaskedNumNegatableView.java

Min- en maxwaarden

Het MaskedNumberField ondersteunt het instellen van numerieke grenzen met setMin() en setMax(). Deze beperkingen helpen ervoor te zorgen dat invoer van de gebruiker binnen een geldig, verwacht bereik blijft.

Minimumwaarde
Gebruik setMin() om het laagste acceptabele nummer te definiëren:
```
field.setMin(10.0); // Minimumwaarde: 10
```
Als de gebruiker een getal onder deze drempel invoert, wordt dit als ongeldig beschouwd.
Maximumwaarde
Gebruik setMax() om het hoogste acceptabele nummer te definiëren:
```
field.setMax(100.0); // Maximumwaarde: 100
```
Waarden boven deze limiet worden als ongeldig gemarkeerd.

Herstellen van de waarde

Het MaskedNumberField ondersteunt een herstel functie die de waarde van het veld op een vooraf gedefinieerde staat reset. Dit kan nuttig zijn wanneer gebruikers wijzigingen moeten ongedaan maken, per ongeluk bewerkingen moeten terugdraaien, of naar een bekende standaardwaarde moeten terugkeren.

Om dit gedrag in te schakelen, definieer de doelwaarde met setRestoreValue(). Indien nodig kan het veld programmatisch worden gereset met restoreValue().

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

Manieren om de waarde te herstellen

Programmatisch met restoreValue()
Via toetsenbord, door op ESC te drukken (dit is de standaard hersteltoets, tenzij overschreven)

De herstelwaarde moet expliciet worden ingesteld. Als deze niet gedefinieerd is, zal de functie het veld niet terugdraaien.

Toon Code

MaskedNumRestoreView.java