# GridLayout

> Grade de colunas por fração, uma altura de linha por conteúdo mais alto.

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

# GridLayout

Arranja os filhos em uma **grade**: cada linha tem sua própria divisão de **colunas por fração**, e a
altura da linha vem do componente mais alto. Ótimo para formulários "rótulo : campo".

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

## Quando usar
- Formulários alinhados (rótulo | campo) com proporção estável.
- Tabelas simples de células.

## Quando NÃO usar
- Uma coluna só → [VerticalLayout](/docs/ui/layouts/vertical-layout).
- Ancorar um componente a outro → [RelativeLayout](/docs/ui/layouts/relative-layout).

## `add(...)` — assinatura e semântica (atenção à ordem!)
```java
public GridLayout add(Object... v)   // TODAS as larguras, depois TODOS os componentes
```
Passe **primeiro todas as larguras**, depois **todos os componentes** (mesma quantidade):

| Largura | Significado |
|---|---|
| `> 0` (ex. `0.35f`) | **fração** da largura da grade (35%) |
| `LAY_AUTO` (`0f`) | largura **automática** (a célula usa o tamanho do conteúdo) |

## Construtores
| Construtor | Descrição |
|---|---|
| `new GridLayout()` | alinhamento `START`/`START` |
| `new GridLayout(Position h, Position v)` | alinhamento horizontal/vertical das linhas |

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

      GridLayout form = new GridLayout(Position.START, Position.START);
      // rótulo (35%) | campo (65%) — larguras primeiro, componentes depois:
      form.add(0.35f, 0.65f, new Label("Nome"),     new TextField(""));
      form.add(0.35f, 0.65f, new Label("E-mail"),   new TextField(""));
      form.add(0.35f, 0.65f, new Label("Telefone"), new TextField(""));

      Component painel = new Component();
      painel.setLayout(form);

      setLayout(new VerticalLayout(Position.START, Position.START));
      add(LAY_AUTO, new Label("Cadastro"));
      add(LAY_FILL, painel);
   }
}
```

> 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
GridLayout form = new GridLayout(Position.START, Position.START);
// rótulo (35%) | campo (65%) — larguras primeiro, componentes depois:
form.add(0.35f, 0.65f, new Label("Nome"),     new TextField(""));
form.add(0.35f, 0.65f, new Label("E-mail"),   new TextField(""));
form.add(0.35f, 0.65f, new Label("Telefone"), new TextField(""));

Component painel = new Component();
painel.setLayout(form);
```

## Como arranja
```
┌───────────┬──────────────────────┐
│ Nome (35%)│ [campo]        (65%)  │  ← linha 1
├───────────┼──────────────────────┤
│ E-mail    │ [campo]              │  ← linha 2
└───────────┴──────────────────────┘
```

## Boas práticas
- As frações de uma linha **somam ~1.0** para cobrir a largura.
- Linhas podem ter **números de colunas diferentes** (cada `add` define uma linha).

## Erros comuns
- **Intercalar** largura e componente: `add(0.35f, label, 0.65f, field)` → lança `UIException`.
  O correto é `add(0.35f, 0.65f, label, field)` (larguras juntas, depois componentes).
- Número de larguras ≠ número de componentes → `UIException` (`cols*2 == args`).

## Veja também
- [VerticalLayout](/docs/ui/layouts/vertical-layout) · [RelativeLayout](/docs/ui/layouts/relative-layout) · [Responsividade](/docs/ui/layouts/responsiveness)