# RelativeLayout

> Positions and sizes by anchors — relative to the container or to another component.

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

# RelativeLayout

Positions each child by **anchors** — relative to the container **or to another component**. Its
unique strength is **anchoring A to B** (a badge in the corner of an avatar, a label to the right of an icon).

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

## When to use
- Anchoring one component to **another** (`AFTER`, `BEFORE`, `END_OF`, `CENTER_OF`).
- Overlays and fine compositions (badge, seal, positioned label).

## When NOT to use
- The "top/content/bottom filling the remainder" skeleton → **prefer** [VerticalLayout](/docs/ui/layouts/vertical-layout)
  with `LAY_FILL` (simpler; see the note about `FILL`/`FIT` below).

## `add(...)` — signature and semantics
```java
public RelativeLayout add(Component alvo, RelPos x, RelPos y, RelSize larg, RelSize alt);
// + overloads:  (..., Component ref)   (..., Gap outgap)   (..., Component ref, Gap outgap)
```
Without `ref`, the anchor is relative to the **previous component** added.

**`RelPos`** (position, in `UIConstants`): `START`, `CENTER`, `END`, `AFTER`, `BEFORE`, `CENTER_OF`,
`END_OF`, `SAMEPOS`, `AUTOPOS`, `AUTOPOSCENTERED`, `KEEPPOS`.

**`RelSize`** (size): `AUTOSIZE`, `FILL`, `FIT`, `SAMESIZE`, `KEEPSIZE`.

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

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

/** 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();

      // Avatar + badge at the avatar corner + name alongside
      RelativeLayout rl = new RelativeLayout();
      Label avatar = new Label("👤");
      avatar.getStyle().autoWidth(Relative.ofFont(3f)).autoHeight(Relative.ofFont(3f));
      Label badge = new Label("9");
      Label nome  = new Label("Ana Silva");

      rl.add(avatar, RelPos.START,  RelPos.START,     RelSize.AUTOSIZE, RelSize.AUTOSIZE);
      rl.add(badge,  RelPos.END_OF, RelPos.START,     RelSize.AUTOSIZE, RelSize.AUTOSIZE, avatar); // avatar corner
      rl.add(nome,   RelPos.AFTER,  RelPos.CENTER_OF, RelSize.AUTOSIZE, RelSize.AUTOSIZE, avatar); // after the avatar

      Component cabecalho = new Component();
      cabecalho.setLayout(rl);

      setLayout(new VerticalLayout(Position.START, Position.START));
      add(LAY_AUTO, cabecalho);
      add(LAY_FILL, new Component());
   }
}
```

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

## Basic usage
```java
// Avatar + badge at the avatar corner + name alongside
RelativeLayout rl = new RelativeLayout();
ImageView avatar = new ImageView(/* photo */);
avatar.getStyle().autoWidth(Relative.ofFont(3f)).autoHeight(Relative.ofFont(3f));
Label badge = new Label("9");
Label nome  = new Label("Ana Silva");

rl.add(avatar, RelPos.START,  RelPos.START,     RelSize.AUTOSIZE, RelSize.AUTOSIZE);
rl.add(badge,  RelPos.END_OF, RelPos.START,     RelSize.AUTOSIZE, RelSize.AUTOSIZE, avatar); // avatar corner
rl.add(nome,   RelPos.AFTER,  RelPos.CENTER_OF, RelSize.AUTOSIZE, RelSize.AUTOSIZE, avatar); // after the avatar

Component cabecalho = new Component();
cabecalho.setLayout(rl);
```

## Useful anchor patterns
- **B to the right of A, aligned:** `add(b, RelPos.AFTER, RelPos.CENTER_OF, RelSize.AUTOSIZE, RelSize.AUTOSIZE, a)`.
- **Same size as A:** `RelSize.SAMESIZE`.
- **Centered card:** `add(card, RelPos.CENTER, RelPos.CENTER, RelSize.AUTOSIZE, RelSize.AUTOSIZE)`.
- **Margin by rule:** pass a `Gap.ofFont(0.5f)` as the last argument (it becomes the rule's `outgap`).

## ⚠️ Exact semantics of `RelSize` (don't confuse them)
- **`FILL`** = **full width/height of the parent** minus the margin — **ignores the reference** (it is not "the
  remaining space next to A").
- **`FIT`** = from the **parent's corner to the reference's edge** (e.g. fill **up to** A's left/top).
- For "one child absorbs the remainder next to the others" → use `HorizontalLayout`/`VerticalLayout` with
  `LAY_FILL`, **not** `RelativeLayout`.

## Common mistakes
- Expecting `FILL` to be "what's left next to A" (it is the whole parent).
- Reference **cycles** (A depends on B which depends on A) — always anchor to components already
  added before.

## See also
- [VerticalLayout](/docs/ui/layouts/vertical-layout) (for the screen skeleton) · [Responsiveness](/docs/ui/layouts/responsiveness)