For AI agents: the "Reading aid" section on this page contains the raw Markdown source identical to the rendered content, with HTML markup and animations removed. AI is advised to read that section directly to understand the content quickly and with less noise.
## Layout (base)

```cpp
class Layout : public UIElement { bool UseCache() const override { return false; } };
```
- Layout containers **never cache**.

## ColumnBox (vertical) / RowBox (horizontal)

```cpp
enum class LayoutAlignment { Start, Center, End, Stretch };
enum class Justify { Start, Center, End, SpaceBetween, SpaceAround };
ColumnBox(); RowBox();
void AddChild(std::shared_ptr<UIElement>);  void ClearChildren();
void RemoveChild(std::shared_ptr<UIElement>);  void RemoveChildAt(int);  void InsertChild(int, std::shared_ptr<UIElement>);
void SetSpacing(float);
void SetJustify(Justify);              // main axis: Start/Center/End/SpaceBetween/SpaceAround
void SetCrossAlign(LayoutAlignment);   // cross axis; Stretch is the compatibility default
```
- `ColumnBox` fills width, no vertical stretch; `RowBox` the opposite.
- `Justify` distributes leftover only when no child is flex/stretching; `CrossAlign` set to Center/Start/End uses the child's desiredSize instead of forcing a fill.

###block_red_start
**Pitfall**

- `AddChild` calls `SetParent(this)`; the container owns via `shared_ptr`. If a child sets an explicit `SetHeight`, leftover space is **added on top** by weight.
###block_red_end

- **`Version`**: leftover distribution by child stretch weight since `v1.17.0`.

## GridLayout

```cpp
using Alignment = LayoutAlignment;   // Start / Center / End / Stretch
void AddChild(std::shared_ptr<UIElement>, int row, int col, int rowSpan=1, int colSpan=1,
              Alignment hAlign=Alignment::Stretch, Alignment vAlign=Alignment::Stretch);
void SetColumnCount(int);  void SetRowCount(int);
void SetSpacing(float h, float v);
void SetColumnStretch(int col, float weight);  void SetRowStretch(int row, float weight);
void SetHorizontalAlignment(Alignment);        void SetVerticalAlignment(Alignment);
void SetCellAlignment(int row, int col, Alignment h, Alignment v);
```
- Row/column counts come from `SetColumnCount/SetRowCount` (or `SetColumnStretch/SetRowStretch`); **empty tracks still exist**, so no placeholder children are needed.
- `SetCellAlignment` controls how a child sits inside its own cell (default `Stretch`); `SetHorizontalAlignment/SetVerticalAlignment` align the whole grid content in the leftover space.
- A 1×1 grid can also use content alignment; `SetColumnStretch(2, ...)` creates a third column.
- Without explicit row/col stretch, the cell weight is the **max** of spanned children's weights.
- **`Version`**: since `v1.26.0`, an explicit `SetWidth/SetHeight` on the Grid is also used as the cell measurement scope; it no longer reports 260 while arranging rows at 274+.

## LayoutHost / Card / Page

```cpp
class LayoutHost : public UIElement {
    std::shared_ptr<UIElement> GetLayout() const;  void SetLayout(...);
    std::shared_ptr<UIElement> GetContent() const; void SetContent(...);   // single-content alias
    void SetContentAlignment(LayoutAlignment h, LayoutAlignment v);        // default Stretch
};
class Card : public LayoutHost { DefaultPadding=12; DefaultCornerRadius=8; ... };
void SetContent(const std::wstring& title, const std::wstring& description, std::shared_ptr<UIElement> action=nullptr);
class Page : public LayoutHost { DefaultPadding=10; ... };
void Page::SetScrollableContent(std::shared_ptr<UIElement> content);   // one line: wrap in ScrollViewer(fill)+8px
```
- `LayoutHost` is a single-content host; `Card` is a rounded/bordered/hover card; `Page` is the page container for `TabView`/`PageHost`.
- `SetContentAlignment(Center, Center)` centers Page/Card content; default `Stretch` keeps old behaviour.
- With no content, explicit `SetWidth/SetHeight` on `Card/Page` still applies; a `ScrollViewer` without content also returns its explicit/finite viewport size.
- `Card::UseCache()` = `HasShadow()`; `Page::UseCache()` = false.

## PageHost (page host / transitions)

```cpp
enum class TransitionDirection { Left, Right, Up, Down };
enum class TransitionEasing { Linear, EaseInOut, EaseOut };
void AddPage(std::shared_ptr<Page>);  void RemovePage(int);  void ClearPages();
void NavigateTo(int index);   void SetCurrentIndexInstant(int index);
void SetTransitionDirection(...);  void SetTransitionEasing(...);  void SetAnimationDuration(float);
int GetCurrentIndex() const;  std::shared_ptr<Page> GetCurrentPage() const;
```
- During a transition it returns **both** source and target pages as visible children; `UpdateAnimation` updates each page only once (otherwise double speed).

###block_red_start
**Pitfall**

- `NavigateTo` is **asynchronous** (switches after the animation); `GetCurrentPage()`/`GetCurrentIndex()` may still be old during it.
- show/hide page content with `SetVisible()` (it calls `InvalidateLayout()`); do not poke the internal visibility flag, or it will be neither re-measured nor repainted.
###block_red_end

- **`Version`**: easing `v1.8.1`; **delayed hidden-page cache release (~1.2 s, recursive)** = `v1.18.0`; `MeasureOverride` **measures every page** = `v1.23.1` — page content shown/hidden at runtime (e.g. an `Expander` card revealed after a combo-box selection) re-lays out and hit-tests immediately, with no need to resize the window.

## TabView

See the "Containers & Scrolling / Tabs" chapter.
Chapter 7

Layout system

Layout, ColumnBox, RowBox, GridLayout, Card, Page, PageHost

Layout (base)

cpp
class Layout : public UIElement { bool UseCache() const override { return false; } };

ColumnBox (vertical) / RowBox (horizontal)

cpp
enum class LayoutAlignment { Start, Center, End, Stretch };
enum class Justify { Start, Center, End, SpaceBetween, SpaceAround };
ColumnBox(); RowBox();
void AddChild(std::shared_ptr<UIElement>);  void ClearChildren();
void RemoveChild(std::shared_ptr<UIElement>);  void RemoveChildAt(int);  void InsertChild(int, std::shared_ptr<UIElement>);
void SetSpacing(float);
void SetJustify(Justify);              // main axis: Start/Center/End/SpaceBetween/SpaceAround
void SetCrossAlign(LayoutAlignment);   // cross axis; Stretch is the compatibility default

Pitfall

  • AddChild calls SetParent(this); the container owns via shared_ptr. If a child sets an explicit SetHeight, leftover space is added on top by weight.

GridLayout

cpp
using Alignment = LayoutAlignment;   // Start / Center / End / Stretch
void AddChild(std::shared_ptr<UIElement>, int row, int col, int rowSpan=1, int colSpan=1,
              Alignment hAlign=Alignment::Stretch, Alignment vAlign=Alignment::Stretch);
void SetColumnCount(int);  void SetRowCount(int);
void SetSpacing(float h, float v);
void SetColumnStretch(int col, float weight);  void SetRowStretch(int row, float weight);
void SetHorizontalAlignment(Alignment);        void SetVerticalAlignment(Alignment);
void SetCellAlignment(int row, int col, Alignment h, Alignment v);

LayoutHost / Card / Page

cpp
class LayoutHost : public UIElement {
    std::shared_ptr<UIElement> GetLayout() const;  void SetLayout(...);
    std::shared_ptr<UIElement> GetContent() const; void SetContent(...);   // single-content alias
    void SetContentAlignment(LayoutAlignment h, LayoutAlignment v);        // default Stretch
};
class Card : public LayoutHost { DefaultPadding=12; DefaultCornerRadius=8; ... };
void SetContent(const std::wstring& title, const std::wstring& description, std::shared_ptr<UIElement> action=nullptr);
class Page : public LayoutHost { DefaultPadding=10; ... };
void Page::SetScrollableContent(std::shared_ptr<UIElement> content);   // one line: wrap in ScrollViewer(fill)+8px

PageHost (page host / transitions)

cpp
enum class TransitionDirection { Left, Right, Up, Down };
enum class TransitionEasing { Linear, EaseInOut, EaseOut };
void AddPage(std::shared_ptr<Page>);  void RemovePage(int);  void ClearPages();
void NavigateTo(int index);   void SetCurrentIndexInstant(int index);
void SetTransitionDirection(...);  void SetTransitionEasing(...);  void SetAnimationDuration(float);
int GetCurrentIndex() const;  std::shared_ptr<Page> GetCurrentPage() const;

Pitfall

  • NavigateTo is asynchronous (switches after the animation); GetCurrentPage()/GetCurrentIndex() may still be old during it.
  • show/hide page content with SetVisible() (it calls InvalidateLayout()); do not poke the internal visibility flag, or it will be neither re-measured nor repainted.

TabView

See the "Containers & Scrolling / Tabs" chapter.

↑