# GridLayout

> Grid of columns by fraction, one row height per tallest content.

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

# GridLayout

Arranges children in a **grid**: each row has its own split of **columns by fraction**, and the row
height comes from the tallest component. Great for "label : field" forms.

> 🟡 · **Package:** `dev.crossfly.ui.layout` · **Extends:** `Layout`

## When to use
- Aligned forms (label | field) with a stable ratio.
- Simple tables of cells.

## When NOT to use
- A single column → [VerticalLayout](/docs/ui/layouts/vertical-layout).
- Anchoring one component to another → [RelativeLayout](/docs/ui/layouts/relative-layout).

## `add(...)` — signature and semantics (mind the order!)
```java
public GridLayout add(Object... v)   // ALL the widths, then ALL the components
```
Pass **all widths first**, then **all components** (same count):

| Width | Meaning |
|---|---|
| `> 0` (ex. `0.35f`) | **fraction** of the grid width (35%) |
| `LAY_AUTO` (`0f`) | **automatic** width (the cell uses the content's size) |

## Constructors
| Constructor | Description |
|---|---|
| `new GridLayout()` | `START`/`START` alignment |
| `new GridLayout(Position h, Position v)` | horizontal/vertical alignment of the rows |

## Full example (copy, paste and run)
```java
package com.exemplo;

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

/** Runnable main screen. Point the launcher (classname) and run: gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();

      GridLayout form = new GridLayout(Position.START, Position.START);
      // label (35%) | field (65%) — widths first, components after:
      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);
   }
}
```

> The snippets below show **only the core** (what goes inside `onShow()`). To run them, place them in the `MainWindow` skeleton above.

## Basic usage
```java
GridLayout form = new GridLayout(Position.START, Position.START);
// label (35%) | field (65%) — widths first, components after:
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);
```

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

## Best practices
- A row's fractions **add up to ~1.0** to cover the width.
- Rows may have **different column counts** (each `add` defines a row).

## Common mistakes
- **Interleaving** width and component: `add(0.35f, label, 0.65f, field)` → throws `UIException`.
  The correct form is `add(0.35f, 0.65f, label, field)` (widths together, then components).
- Number of widths ≠ number of components → `UIException` (`cols*2 == args`).

## See also
- [VerticalLayout](/docs/ui/layouts/vertical-layout) · [RelativeLayout](/docs/ui/layouts/relative-layout) · [Responsiveness](/docs/ui/layouts/responsiveness)