# How to create a currency field

> A field with automatic monetary formatting, decimal places, and reading of the numeric value.

Source: https://crossfly.dev/docs/cookbook/forms/mascara-moeda — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# How to create a currency field

**Purpose.** Create a field that formats monetary values from right to left (the user types `12345` and sees `123,45`), with thousands grouping and decimal places according to the locale, and retrieve the value as a decimal number for calculation.

## APIs used
- `campo.setMode(EditMode.CURRENCY, true)` — turns on currency mode with `maskedEdit`. Automatically derives: `validChars = "0123456789.+-"`, `textAlignment = END` (right-aligned), `keyboard = CALCULATOR` and, if there is no mask, `mask = TextField.getDefaultCurrencyMask(decimalPlaces)`.
- `campo.<TextFieldStyle>getStyle().decimalPlaces(2)` — number of decimal places (default `2`). Set it **before** `setMode`, since the default mask is built from it.
- `TextField.getDefaultCurrencyMask(int decimalPlaces)` — generates the default mask using `LocaleFormats.thousandsSeparator` and `LocaleFormats.decimalSeparator` (e.g., `999.999.999,99` in pt-BR).
- `TextField.getText()` — formatted value for display (`"1.234,56"`).
- `TextField.getTextWithoutMask()` — value with a decimal point, ready for `Double.parseDouble` (`"1234.56"`). Respects the negative sign.

> Negative sign: in currency mode with a mask, typing `-` or `+` toggles the sign without inserting a character (`handleCharInput`). The negative appears in `getTextWithoutMask()` as a `-` prefix.

> Separators come from the locale via `LocaleFormats` (populated at initialization). Do not hardcode `,`/`.` in the code — use `getDefaultCurrencyMask` or `setMode(CURRENCY, true)` to respect the region.

## Complete example (copy, paste, and run)
```java
package com.exemplo;

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;
import dev.crossfly.ui.style.*;   // TextFieldStyle (config on the style)

/** Runnable main screen. Point the launcher (classname) and run: gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();
      setLayout(new VerticalLayout());

      TextField valor = new TextField("");
      valor.caption("Valor");
      valor.<TextFieldStyle>getStyle().decimalPlaces(2); // set before setMode
      valor.setMode(EditMode.CURRENCY, true);            // currency + mask + calculator keyboard
      valor.setText("1234.56");                          // displays "1.234,56" (pt-BR)

      Label resultado = new Label("");

      Button somar = new Button("Somar 10");
      somar.onAction(o ->
      {
         double v = Double.parseDouble(valor.getTextWithoutMask()); // 1234.56
         double total = v + 10;
         resultado.setText("Total: " + total);
      });

      add(LAY_FILL, valor);
      add(LAY_AUTO, somar);
      add(LAY_FILL, resultado);
   }
}
```

> The snippet below shows **only the core**. To run it, place it in the `MainWindow` skeleton above.

## Minimal snippet
```java
import dev.crossfly.ui.*;
import dev.crossfly.ui.style.*;
import static dev.crossfly.ui.UIConstants.EditMode;

TextField valor = new TextField("");
valor.caption("Valor");
valor.<TextFieldStyle>getStyle().decimalPlaces(2); // set before setMode
valor.setMode(EditMode.CURRENCY, true);            // currency + mask + calculator keyboard

// initial value:
valor.setText("1234.56"); // displays "1.234,56" (pt-BR)

Button somar = new Button("Somar");
somar.onAction(o ->
{
   double v = Double.parseDouble(valor.getTextWithoutMask()); // 1234.56
   // ... calculation
});
```

For a custom mask (e.g., 3 explicit decimal places):
```java
valor.<TextFieldStyle>getStyle()
   .mask(TextField.getDefaultCurrencyMask(3)); // then setMode(CURRENCY, true)
```

## Dig deeper
- [Masks and keyboards](/docs/ui/forms-and-input/masks-and-keyboards) · [Text fields](/docs/ui/forms-and-input/text-fields)
- Sibling recipes: [CPF/ZIP/date mask](/docs/cookbook/forms/mascara-cpf) · [Numeric keyboard](/docs/cookbook/forms/teclado-numerico)
- Canonical source: Chapter 14 — Basic widgets · [Enums (UIConstants)](/docs/reference/enums-uiconstants)