# VerticalLayout

> Stacks children top to bottom, each at the container's width.

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

# VerticalLayout

Stacks child components **top to bottom** (one row per child), each occupying the
**container's width** (minus the margin). It is the most-used layout — the backbone of most screens.

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

## When to use
- Column screens: header + content + footer.
- Any list of stacked sections.

## When NOT to use
- Items side by side → [HorizontalLayout](/docs/ui/layouts/horizontal-layout).
- Label/field grid → [GridLayout](/docs/ui/layouts/grid-layout).

## `add(...)` — signature and semantics
```java
public VerticalLayout add(float altura, Component c)
```
The **`altura`** parameter controls the row:

| Value | Meaning |
|---|---|
| `LAY_AUTO` (`0f`) | component's **natural height** (`getAutoHeight()`) — scales with the font |
| `LAY_FILL` (`-1f`) | **fills the remaining space** (use **one** FILL row per layout) |
| `> 0` (ex. `0.25f`) | **fraction of the container's height** (25%) — not pixels |

## Constructors
| Constructor | Description |
|---|---|
| `new VerticalLayout()` | horizontal alignment **centered** for each row |
| `new VerticalLayout(Position h, Position v)` | `h` = horizontal alignment of the rows (`START`/`CENTER`/`END`) |

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

      setLayout(new VerticalLayout(Position.START, Position.START));

      Component lista = new Component();          // elastic content (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"));   // header — natural height
      add(LAY_FILL, lista);                    // content — absorbs all the leftover
      add(LAY_AUTO, new Button("Adicionar"));  // footer — natural height
   }
}
```

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

## Basic usage
```java
setLayout(new VerticalLayout(Position.START, Position.START));
add(LAY_AUTO, new Label("Produtos"));   // header — natural height
add(LAY_FILL, lista);                    // content — absorbs all the leftover
add(LAY_AUTO, new Button("Adicionar"));  // footer — natural height
```

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

## Best practices
- **1 `LAY_FILL` row + the rest `LAY_AUTO`** is the most robust arrangement (it doesn't break if the font
  grows or the keyboard opens).
- Spacing rows: insert `add(LAY_AUTO, Gap.ofFont(0.25f))` as a spacer (the `Gap` counts as a
  row of half a font's height).

## Common mistakes
- Giving **a fraction to every** row (`add(0.2f, …)` on everything) — fragile; prefer auto + 1 fill.
- Thinking `add(0.7f, x)` is 70% of the **remainder** — it is 70% of the container's **total height**.
- More than one `LAY_FILL` row — only the last one prevails.

## See also
- [HorizontalLayout](/docs/ui/layouts/horizontal-layout) · [GridLayout](/docs/ui/layouts/grid-layout) · [Responsiveness](/docs/ui/layouts/responsiveness)