# Como exibir um popup de seleção modal

> Abrir uma lista como janela modal centralizada com linhas customizadas via ItemFactory.

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

# Como exibir um popup de seleção modal

**Propósito.** Abrir uma lista de seleção como **janela flutuante** (não embutida no layout).
`ListViewWindow` embrulha um `ListView` dentro de um `Window`, centraliza-o na tela e o fecha
sozinho quando o usuário seleciona. Serve tanto para seleção simples quanto para linhas com
aparência customizada.

## APIs usadas
- `new ListViewWindow(String[] items, ListViewWindow.ItemType type)` — cria o popup; há também a sobrecarga com `String title`.
- `ListViewWindow.ItemType.SINGLE` / `MULTIPLE` — **enum próprio** de `ListViewWindow` (alias de `ListView.ItemType`, convertido internamente por `toPanel()`).
- `ListViewWindow.size(float widthRatio, float heightRatio)` — tamanho como fração da tela (defaults `0.5f`, `0.5f`); o popup é sempre centralizado.
- `ListViewWindow.onConfirm(Component.Action)` — delega ao `ListView` interno; ao confirmar em SINGLE, a janela se fecha via `closeAction(this::hide)`.
- `ListViewWindow.ItemFactory(ItemFactory factory)` — **atenção: método com inicial maiúscula**. A interface é `ItemFactory { Component create(String text, int index) throws Exception; }`.
- `ListViewWindow.show()` / `hide()` — herdados de `Window` (empilha/desempilha no `EventsProcessor`).
- `ListViewWindow.getSelectedText()` / `getSelectedIndex()` / `getSelectedTexts()` — delegados ao painel interno.
- `ListViewWindow.getPanel()` — acesso ao `ListView` subjacente, se precisar de config avançada.

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

      final String[] paises = {"Brasil", "Portugal", "Angola", "Moçambique"};

      // ListViewWindow é popup: NÃO entra no layout — abre com show() disparado por um Button
      Button abrir = new Button("Escolher país");
      abrir.onClick(e ->
      {
         ListViewWindow popup = new ListViewWindow("País", paises, ListViewWindow.ItemType.SINGLE);
         popup.size(.6f, .5f);                 // 60% da largura, 50% da altura da tela
         popup.onConfirm(ev ->
         {
            String pais = popup.getSelectedText();   // janela já se fecha sozinha em SINGLE
            Debug.log("País: " + pais);
            return null;
         });
         popup.show();                          // abre modal centralizado
         return null;
      });

      add(LAY_AUTO, abrir);
   }
}
```

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

## Trecho mínimo
```java
// verificado na fonte: ListViewWindow.java
String[] paises = {"Brasil", "Portugal", "Angola", "Moçambique"};

ListViewWindow popup = new ListViewWindow("País", paises, ListViewWindow.ItemType.SINGLE);
popup.size(.6f, .5f);                 // 60% da largura, 50% da altura da tela
popup.onConfirm(e ->
{
   String pais = popup.getSelectedText();   // janela já se fecha sozinha em SINGLE
   return null;
});
popup.show();                          // abre modal centralizado
```

Linhas customizadas com `ItemFactory` (note o **`I` maiúsculo** no nome do método):

```java
// verificado na fonte: ListViewWindow.ItemFactory (interface) + método ItemFactory(...)
ListViewWindow popup = new ListViewWindow("Contato", nomes, ListViewWindow.ItemType.SINGLE);
popup.ItemFactory((text, index) ->
{
   Component linha = new Component();
   linha.setLayout(new GridLayout());
   linha.add(new Label(text));                 // monte a linha como quiser
   return linha;
});
popup.onConfirm(e -> { /* ... */ return null; });
popup.show();
```

> Divergência Javadoc × código: o Javadoc de classe mostra `sel.show()` sobre um `ListView`, mas
> `show()`/`hide()` existem em `Window` — portanto no `ListViewWindow`, não no `ListView`. Para o
> modo popup use sempre `ListViewWindow`.

## Aprofunde-se
- Versão embutida (sem janela) da mesma lista: [lista-simples.md](/docs/cookbook/lists/lista-simples).
- Guia de widget: [ListViewWindow](/docs/ui/widgets/listviewwindow) · Fonte canônica: Capítulo 15