# TimePicker

> Seleção de hora e minuto por relógio analógico ou grade.

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

# TimePicker

`TimePicker` seleciona **hora e minuto** via dois relógios analógicos (horas à esquerda, minutos à direita) com ponteiros arrastáveis, ou via uma **grade numérica** (modo lista). Confirma por três botões: manhã (AM), tarde (PM) e hora atual. Segue o padrão dos pickers (ver [`Picker`](/docs/ui/widgets/picker)).

> 🟡 · **Pacote:** `dev.crossfly.ui.picker` · **Estende:** `Picker` · **Estilo:** `TimePickerStyle`

## Quando usar
- Coletar um horário (`HH:MM`).

## Quando NÃO usar
- Coletar data → use [`DatePicker`](/docs/ui/widgets/datepicker).

## Aparência
Display grande no topo (`hh:mm`), botão de toggle relógio/grade, a área dos relógios (ou grade numérica) e uma linha de botões `Manhã` / `Tarde` / `Atual`. Dimensiona-se em ~85% de `Screen.minSize`.

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

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

/** 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());

      Button abrir = new Button("Escolher hora");
      abrir.onAction(c ->
      {
         TimePicker tp = new TimePicker().setTime(8, 30);
         tp.show(answer -> Hint.show("Hora: " + (String) answer, 2000)); // "08:30"
      });
      add(LAY_AUTO, abrir);
   }
}
```

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

## Uso básico
```java
TimePicker tp = new TimePicker();
tp.show(answer -> campoHora.setText((String) answer)); // "08:30"
```

## Construtores
| Construtor | Descrição |
|---|---|
| `TimePicker()` | Sem parâmetros; inicia na hora atual. |

## Propriedades e personalização
| Método | Tipo | O que faz |
|---|---|---|
| `setTime(int hour, int minute)` | 0-23 / 0-59 (clamp) | Pré-define a hora. **Chame antes de `show()`.** |
| `timeStyle(TimePickerStyle)` | estilo | Estilo customizado. |
| `getHour()` / `getMinute()` | `int` | Hora (0-23) / minuto. |
| `getTimeText()` | `String` | `HH:MM` (24h) com `LocaleFormats.timeSeparator`. |

## Callbacks e eventos
| Callback | Quando dispara |
|---|---|
| `onSelect(Action)` | ao confirmar (recebe o `TimePicker`). |
| `show(onAnswer)` | ao fechar, entrega a `String` `HH:MM`. |

`getAnswer()` devolve sempre **24h** `HH:MM`. Os rótulos e o separador respeitam `LocaleFormats.is24Hour`/`timeSeparator`.

## Estados
- Modo relógio (`listMode=false`) ou grade numérica (`listMode=true`), alternados pelo toggle.
- `hide()` é sobrescrito para **parar o timer** de "hora atual" antes de fechar.

### Pré-definir e reagir à seleção
```java
TimePicker tp = new TimePicker().setTime(8, 30);
tp.onSelect(p -> Debug.log("Escolhido: " + ((TimePicker) p).getTimeText()));
tp.show(answer -> campoHora.setText((String) answer)); // "08:30"
```

## Boas práticas
- Chame `setTime` **antes** de `show()` — os ângulos são lidos em `onShow`.
- O resultado é sempre 24h; converta para 12h no display do app se precisar.

## Erros comuns
- **`setTime` depois de `show()`** — não reflete na UI já construída.
- **Assumir formato 12h no `answer`** — é sempre `HH:MM` 24h.

## Veja também
- Guia da área: [`ui/`](/docs/ui) · Receitas: [`cookbook/`](/docs/cookbook)
- Base do padrão: [`Picker`](/docs/ui/widgets/picker)
- Componentes relacionados: [`DatePicker`](/docs/ui/widgets/datepicker)