# VerticalLayout

> Empilha os filhos de cima para baixo, cada um na largura do contêiner.

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

# VerticalLayout

Empilha os componentes-filhos **de cima para baixo** (uma linha por filho), cada um ocupando a
**largura do contêiner** (menos a margem). É o layout mais usado — a espinha dorsal da maioria das telas.

> 🟢 · **Pacote:** `dev.crossfly.ui.layout` · **Estende:** `Layout`

## Quando usar
- Telas em coluna: cabeçalho + conteúdo + rodapé.
- Qualquer lista de seções empilhadas.

## Quando NÃO usar
- Itens lado a lado → [HorizontalLayout](/docs/ui/layouts/horizontal-layout).
- Grade rótulo/campo → [GridLayout](/docs/ui/layouts/grid-layout).

## `add(...)` — assinatura e semântica
```java
public VerticalLayout add(float altura, Component c)
```
O parâmetro **`altura`** controla a linha:

| Valor | Significado |
|---|---|
| `LAY_AUTO` (`0f`) | **altura natural** do componente (`getAutoHeight()`) — escala com a fonte |
| `LAY_FILL` (`-1f`) | **preenche a sobra** (use **uma** linha FILL por layout) |
| `> 0` (ex. `0.25f`) | **fração da altura do contêiner** (25%) — não são pixels |

## Construtores
| Construtor | Descrição |
|---|---|
| `new VerticalLayout()` | alinhamento horizontal **centralizado** de cada linha |
| `new VerticalLayout(Position h, Position v)` | `h` = alinhamento horizontal das linhas (`START`/`CENTER`/`END`) |

## 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(Position.START, Position.START));

      Component lista = new Component();          // conteúdo elástico (placeholder)
      lista.setLayout(new VerticalLayout(Position.START, Position.START));
      for (int i = 1; i <= 5; i++)
         lista.add(LAY_AUTO, new Label("Produto " + i));

      add(LAY_AUTO, new Label("Produtos"));   // cabeçalho — altura natural
      add(LAY_FILL, lista);                    // conteúdo — absorve toda a sobra
      add(LAY_AUTO, new Button("Adicionar"));  // rodapé — altura natural
   }
}
```

> 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
setLayout(new VerticalLayout(Position.START, Position.START));
add(LAY_AUTO, new Label("Produtos"));   // cabeçalho — altura natural
add(LAY_FILL, lista);                    // conteúdo — absorve toda a sobra
add(LAY_AUTO, new Button("Adicionar"));  // rodapé — altura natural
```

## Como arranja
```
┌──────────────────────────┐
│ Label   (LAY_AUTO)        │  ← altura natural
├──────────────────────────┤
│                          │
│ lista   (LAY_FILL)       │  ← preenche o que sobrou
│                          │
├──────────────────────────┤
│ Button  (LAY_AUTO)        │  ← altura natural
└──────────────────────────┘
```

## Boas práticas
- **1 linha `LAY_FILL` + as demais `LAY_AUTO`** é o arranjo mais robusto (não quebra se a fonte
  crescer ou o teclado abrir).
- Espaçar linhas: insira `add(LAY_AUTO, Gap.ofFont(0.25f))` como espaçador (o `Gap` conta como uma
  linha de meia altura de fonte).

## Erros comuns
- Dar **fração a todas** as linhas (`add(0.2f, …)` em tudo) — frágil; prefira auto + 1 fill.
- Achar que `add(0.7f, x)` é 70% da **sobra** — é 70% da **altura total** do contêiner.
- Mais de uma linha `LAY_FILL` — só a última prevalece.

## Veja também
- [HorizontalLayout](/docs/ui/layouts/horizontal-layout) · [GridLayout](/docs/ui/layouts/grid-layout) · [Responsividade](/docs/ui/layouts/responsiveness)