# TimePicker

> Selección de hora y minuto mediante reloj analógico o cuadrícula.

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

# TimePicker

`TimePicker` selecciona **hora y minuto** mediante dos relojes analógicos (horas a la izquierda, minutos a la derecha) con manecillas arrastrables, o mediante una **cuadrícula numérica** (modo lista). Confirma con tres botones: mañana (AM), tarde (PM) y hora actual. Sigue el patrón de los pickers (ver [`Picker`](/docs/ui/widgets/picker)).

> 🟡 · **Paquete:** `dev.crossfly.ui.picker` · **Extiende:** `Picker` · **Estilo:** `TimePickerStyle`

## Cuándo usar
- Recolectar un horario (`HH:MM`).

## Cuándo NO usar
- Recolectar fecha → usa [`DatePicker`](/docs/ui/widgets/datepicker).

## Apariencia
Display grande en la parte superior (`hh:mm`), botón de conmutación reloj/cuadrícula, el área de los relojes (o cuadrícula numérica) y una fila de botones `Mañana` / `Tarde` / `Actual`. Se dimensiona a ~85% de `Screen.minSize`.

## Ejemplo completo (copiar, pegar y ejecutar)
```java
package com.exemplo;

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

/** Pantalla principal ejecutable. Apunta el launcher (classname) y corre: 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);
   }
}
```

> Los fragmentos siguientes muestran **solo el núcleo** (lo que va dentro de `onShow()`). Para ejecutarlos, colócalos en el esqueleto `MainWindow` de arriba.

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

## Constructores
| Constructor | Descripción |
|---|---|
| `TimePicker()` | Sin parámetros; inicia en la hora actual. |

## Propiedades y personalización
| Método | Tipo | Qué hace |
|---|---|---|
| `setTime(int hour, int minute)` | 0-23 / 0-59 (clamp) | Predefine la hora. **Llámalo antes de `show()`.** |
| `timeStyle(TimePickerStyle)` | estilo | Estilo personalizado. |
| `getHour()` / `getMinute()` | `int` | Hora (0-23) / minuto. |
| `getTimeText()` | `String` | `HH:MM` (24h) con `LocaleFormats.timeSeparator`. |

## Callbacks y eventos
| Callback | Cuándo se dispara |
|---|---|
| `onSelect(Action)` | al confirmar (recibe el `TimePicker`). |
| `show(onAnswer)` | al cerrar, entrega el `String` `HH:MM`. |

`getAnswer()` devuelve siempre **24h** `HH:MM`. Las etiquetas y el separador respetan `LocaleFormats.is24Hour`/`timeSeparator`.

## Estados
- Modo reloj (`listMode=false`) o cuadrícula numérica (`listMode=true`), alternados por el conmutador.
- `hide()` está sobrescrito para **detener el temporizador** de "hora actual" antes de cerrar.

### Predefinir y reaccionar a la selección
```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"
```

## Buenas prácticas
- Llama a `setTime` **antes** de `show()` — los ángulos se leen en `onShow`.
- El resultado es siempre 24h; conviértelo a 12h en el display de la app si lo necesitas.

## Errores comunes
- **`setTime` después de `show()`** — no se refleja en la UI ya construida.
- **Asumir formato 12h en el `answer`** — siempre es `HH:MM` 24h.

## Ver también
- Guía del área: [`ui/`](/docs/ui) · Recetas: [`cookbook/`](/docs/cookbook)
- Base del patrón: [`Picker`](/docs/ui/widgets/picker)
- Componentes relacionados: [`DatePicker`](/docs/ui/widgets/datepicker)