## 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.Layout system
Layout, ColumnBox, RowBox, GridLayout, Card, Page, PageHost
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
ColumnBoxfills width, no vertical stretch;RowBoxthe opposite.Justifydistributes leftover only when no child is flex/stretching;CrossAlignset to Center/Start/End uses the child's desiredSize instead of forcing a fill.
Pitfall
AddChildcallsSetParent(this); the container owns viashared_ptr. If a child sets an explicitSetHeight, leftover space is added on top by weight.
Version: leftover distribution by child stretch weight sincev1.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(orSetColumnStretch/SetRowStretch); empty tracks still exist, so no placeholder children are needed. SetCellAlignmentcontrols how a child sits inside its own cell (defaultStretch);SetHorizontalAlignment/SetVerticalAlignmentalign 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: sincev1.26.0, an explicitSetWidth/SetHeighton 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
LayoutHostis a single-content host;Cardis a rounded/bordered/hover card;Pageis the page container forTabView/PageHost.SetContentAlignment(Center, Center)centers Page/Card content; defaultStretchkeeps old behaviour.- With no content, explicit
SetWidth/SetHeightonCard/Pagestill applies; aScrollViewerwithout 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;
UpdateAnimationupdates each page only once (otherwise double speed).
Pitfall
NavigateTois asynchronous (switches after the animation);GetCurrentPage()/GetCurrentIndex()may still be old during it.- show/hide page content with
SetVisible()(it callsInvalidateLayout()); do not poke the internal visibility flag, or it will be neither re-measured nor repainted.
Version: easingv1.8.1; delayed hidden-page cache release (~1.2 s, recursive) =v1.18.0;MeasureOverridemeasures every page =v1.23.1— page content shown/hidden at runtime (e.g. anExpandercard 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.