# Como usar um Dropdown de seleção

> Abrir uma lista suspensa, reagir à escolha e obter o item selecionado.

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

# Como usar um Dropdown de seleção

**Propósito.** Oferecer seleção única a partir de uma lista de itens, exibida como um
botão com seta que abre um popup (`ListViewWindow`) ao toque. Após escolher, o texto do
Dropdown passa a mostrar o item selecionado. Use para escolher entre poucas/médias
opções sem ocupar espaço fixo na tela.

## APIs usadas
- `new Dropdown(String placeholder, String[] items)` — cria o dropdown com um texto de placeholder e o array de itens.
- `new Dropdown(String[] items)` — variante com placeholder default `"Select..."`.
- `dropdown.onSelect(Component.Action action)` — callback disparado **após** o usuário confirmar a escolha no popup.
- `dropdown.getSelectedIndex()` — índice do item selecionado, ou `-1` se nenhum.
- `dropdown.getSelectedText()` — texto do item selecionado, ou `null` se nenhum.
- `dropdown.setSelectedIndex(int index)` — seleciona programaticamente e atualiza o texto exibido.
- `dropdown.popupHeightRatio(float)` / `dropdown.popupWidthRatio(float)` — ajustam o tamanho do popup relativo à tela.

## 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());

      String[] estados = { "Acre", "Bahia", "São Paulo", "Paraná" };

      Dropdown uf = new Dropdown("Selecione o estado", estados);

      uf.onSelect(origin ->
      {
         int i = uf.getSelectedIndex();       // -1 se nada escolhido
         String texto = uf.getSelectedText(); // null se nada escolhido
         filtrarPorEstado(texto);
      });

      // Pré-seleção programática (opcional)
      uf.setSelectedIndex(2);   // "São Paulo"

      add(0.5f, uf);            // meia largura na linha (GridLayout)
   }

   private void filtrarPorEstado(String estado)
   {
      // ... filtrar a lista conforme o estado escolhido ...
   }
}
```

> O trecho abaixo mostra **só o miolo**. Para rodar, coloque-o no esqueleto `MainWindow` acima.

## Trecho mínimo
```java
String[] estados = { "Acre", "Bahia", "São Paulo", "Paraná" };

Dropdown uf = new Dropdown("Selecione o estado", estados);

uf.onSelect(origin ->
{
   int i = uf.getSelectedIndex();       // -1 se nada escolhido
   String texto = uf.getSelectedText(); // null se nada escolhido
   filtrarPorEstado(texto);
});

// Pré-seleção programática (opcional)
uf.setSelectedIndex(2);   // "São Paulo"

add(0.5f, uf);            // meia largura na linha (GridLayout)
```

> **Nota de verificação (código 2026).** Confirmado na fonte: `Dropdown` estende `Button`;
> construtores `Dropdown(String placeholder, String[] items)` e `Dropdown(String[] items)`;
> `onSelect(Action)`, `getSelectedIndex()`, `getSelectedText()`, `setSelectedIndex(int)`.
> O popup decide sozinho se abre **acima ou abaixo** do dropdown conforme o espaço
> disponível na tela, e fecha ao tocar fora. O callback `onSelect` roda **depois** de o
> `selectedIndex`/`text` já terem sido atualizados, então é seguro chamar
> `getSelectedText()` dentro dele.

## Aprofunde-se
- Página do widget: [Dropdown](/docs/ui/widgets/dropdown) · Fonte canônica: Capítulo 14
- Seleção única/múltipla com marcadores: [checkbox-e-radio.md](/docs/cookbook/ui/checkbox-e-radio)