# Keypad

> Janela de teclado numérico/calculadora que se ancora a um TextField em foco.

Source: https://crossfly.dev/pt/docs/ui/widgets/keypad — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# Keypad

`Keypad` é uma **janela** (`Window`) com um teclado numérico que se ancora acima ou abaixo do campo de texto em foco. Quando em modo calculadora (`isCalculator`), acrescenta uma 4ª coluna com `+ − × ÷ =` e resolve a aritmética digitada, escrevendo o resultado de volta no campo.

O uso é quase sempre **indireto**: você configura `Keyboard.KEYPAD`/`CALCULATOR` (ou `EditMode.CURRENCY`) no [`TextField`](/docs/ui/widgets/textfield) e o próprio campo instancia e exibe o `Keypad` quando ganha foco. Instanciá-lo manualmente é raro.

> 🔴 · **Pacote:** `dev.crossfly.ui` · **Estende:** `Window` · **Estilo:** `KeypadStyle`

## Quando usar
- Entrada numérica embutida (sem depender do teclado nativo), inclusive no desktop.
- Modo calculadora: permitir que o usuário faça contas dentro de um campo monetário/numérico.

## Quando NÃO usar
- Entrada de texto livre → deixe o teclado nativo (`Keyboard.DEFAULT`).
- Você raramente instancia `Keypad` diretamente — configure o teclado no [`TextField`](/docs/ui/widgets/textfield).

## Aparência
Grade de botões (`GridLayout`): 3 colunas (0–9, backspace, enter) ou 4 colunas em modo calculadora (com operadores). Os botões usam `keyWidth`/`keyHeight` (× altura da fonte) e cantos arredondados nas quatro pontas. A janela posiciona-se abaixo do campo se couber, senão acima (ciente do caption flutuante).

``

## Exemplo completo (copiar, colar e rodar)
```java
package com.exemplo;

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;

/** Tela principal executável. Aponte o launcher (classname) e rode: gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();
      setLayout(new VerticalLayout());

      // Campo numérico que receberá as teclas do Keypad
      TextField valor = new TextField().caption("Quantidade");
      add(LAY_AUTO, valor);

      // Label de saída
      Label saida = new Label("Digite no keypad e toque em Confirmar");
      add(LAY_AUTO, saida);

      // Botão que abre o Keypad ancorado ao campo (uso direto)
      Button abrir = new Button("Abrir keypad").onAction(c -> {
         Keypad kp = new Keypad(valor);   // target é o TextField acima
         kp.show();
      });
      add(LAY_AUTO, abrir);

      // O Keypad escreve no campo; leia getText() no envio
      Button confirmar = new Button("Confirmar")
         .onAction(c -> saida.setText("Valor: " + valor.getText()));
      add(LAY_AUTO, confirmar);
   }
}
```

> Os trechos abaixo mostram **só o miolo** (o que vai dentro de `onShow()`). Para rodar, coloque-os no esqueleto `MainWindow` acima.

## Uso básico (indireto, via TextField)
```java
// O TextField exibe o Keypad sozinho ao focar:
TextField valor = new TextField().caption("Quantidade");
valor.setKeyboard(Keyboard.KEYPAD);      // teclado numérico embutido
container.add(LAY_AUTO, valor);

// Modo calculadora — CURRENCY já usa CALCULATOR por padrão:
TextField preco = new TextField().caption("Preço");
preco.setMode(EditMode.CURRENCY, true);
container.add(LAY_AUTO, preco);
```

## Uso direto (avançado)
```java
// Ancorar manualmente um Keypad a um campo:
Keypad kp = new Keypad(campo);   // campo é um TextInput (TextField/TextArea)
kp.show();

// Em modo calculadora:
Keypad calc = new Keypad(campo);
calc.<KeypadStyle>getStyle().isCalculator(true);
calc.show();
```

## Construtores
| Construtor | Descrição |
|---|---|
| `Keypad(TextInput target)` | cria o keypad ancorado ao campo `target` que receberá as teclas |

## Propriedades e personalização (via `KeypadStyle`)
| Propriedade | Tipo | O que faz |
|---|---|---|
| `.isCalculator(boolean)` | `boolean` | 4ª coluna com `+ − × ÷` e botão `=` |
| `.is1to9(boolean)` | `boolean` | ordem das teclas (1-2-3 no topo vs 7-8-9) |
| `.keyWidth` / `.keyHeight` | `float` | tamanho das teclas (× altura da fonte) |
| `.digitColor` / `.specialColor` | ARGB | cor dos dígitos / teclas especiais |
| `.keypadBackColor` | ARGB | fundo das teclas |
| `.enterIcon` / `.backspaceIcon` | `Icon` | ícones de enter e backspace |
| `.radiusTL/TR/BL/BR` | `float` | raios de canto |

## Callbacks e eventos
`Keypad` não expõe `onAction` próprio. Ele envia as teclas ao `target`:
- Dígitos → `target.onKeyTyped(c)`.
- Backspace / Enter → `target.onKeyDown(Input.Keys.BACKSPACE / ENTER)`.
- Em modo calculadora, `=` calcula e escreve o resultado via `target.setText(...)`.
- Ao fechar (`onRemove`), o foco volta ao campo com `restoreFocusAtEnd()`.

Para reagir, observe o **campo** (`getText()`), não o `Keypad`.

## Estados
- **Enter ↔ Equals:** em modo calculadora, o botão inferior alterna entre `Enter` (ícone) e `=` (texto) conforme há operação pendente.
- A janela fecha ao tocar fora ou ao confirmar (`Enter`).

### Campo monetário com calculadora embutida
```java
TextField total = new TextField().caption("Total");
total.setMode(EditMode.CURRENCY, true);   // abre o Keypad em modo calculadora
container.add(LAY_AUTO, total);
// O usuário digita "10 + 5 =" e o campo passa a mostrar 15,00.
```

### Forçar o Keypad no desktop
```java
// NUMERIC no desktop cai para KEYPAD automaticamente em showInput();
// para garantir o Keypad em qualquer plataforma, use KEYPAD explicitamente:
TextField codigo = new TextField().caption("Código");
codigo.setKeyboard(Keyboard.KEYPAD);
container.add(LAY_AUTO, codigo);
```

## Boas práticas
- Prefira **configurar o teclado no `TextField`** (`setKeyboard`/`setMode`) a instanciar `Keypad` diretamente.
- Para entrada monetária, `EditMode.CURRENCY` já traz a calculadora — não é preciso configurar nada além.

## Erros comuns
- **Registrar `onAction` no `Keypad`:** ele não dispara ação própria; observe o campo alvo.
- **Instanciar `Keypad` sem um `target` focável:** ele precisa de um `TextInput` para enviar as teclas.

## Veja também
- Guia da área: [`ui/`](/docs/ui) · Receitas: [`cookbook/`](/docs/cookbook)
- Conceito (teclado virtual, foco): [`concepts/`](/docs/concepts)
- Componentes relacionados: [`TextField`](/docs/ui/widgets/textfield) · [`TextInput`](/docs/ui/widgets/textinput) · [`TextArea`](/docs/ui/widgets/textarea)