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.
## ScrollViewer

```cpp
enum class ScrollBarVisibility { Auto, Always, Hidden };
ZSignal<float,float> ScrollChanged;
void SetContent(std::shared_ptr<UIElement>);
void SetVertical/HorizontalScrollEnabled(bool);
void SetVertical/HorizontalScrollBarVisibility(ScrollBarVisibility);
void SetScrollBarWidth(float);  void SetScrollWheelStep(float);  void SetAnimationSpeed(float);
void ScrollTo(float x,float y,bool animated=true);  void ScrollBy(...);
float GetScrollOffsetX/Y() const;
```

###block_red_start
**Pitfall**

- `Hidden` still allows programmatic/wheel scrolling.
###block_red_end

- **`Version`**: `v1.18.0` — `ScrollViewer::UseCache()==false`.

## ScrollBar (standalone, reusable)

```cpp
std::function<void(float value, bool animate)> ValueChanged;
explicit ScrollBar(bool vertical);
void SetRange(float value, float maxValue, float viewportSize);   // host pushes each frame
void SetBarWidth(float);  void SetMinLength(float);  void SetHitExtra(float);
void SetColors(D2D1_COLOR_F thumb, D2D1_COLOR_F hoverThumb, D2D1_COLOR_F track);
void SetIdleDelay(float);  void SetAutoShrink(bool);  void MarkActive();
inline static float ShrunkWidthRatio;   // default 0.30
```
- Drag → `animate=false`; track click → `animate=true`. Hover expands, idle shrinks; hosts reserve gutter space via `ShrunkWidthRatio`.

###block_red_start
**Pitfall**

- `ValueChanged` is a `std::function` (not `ZSignal`), signature `(float, bool)`.
- the idle-shrink countdown is **not** counted as an active animation — otherwise it put the whole window into animation mode and stopped data repaints from landing. Cost: idle shrink is **lazy** (triggered by the next frame).
###block_red_end

- **`Version`**: reusable since `v1.11.0`; `ShrunkWidthRatio` `v1.13.0`.

## SplitView

```cpp
enum class Orientation { Vertical, Horizontal };   // Vertical = left/right panes + vertical splitter
ZSignal<float> SplitChanged;
void SetFirst/SetSecond(std::shared_ptr<UIElement>);
void SetSplitRatio(float);  void SetSplitterWidth(float);  void SetMinFirst/MinSecond(float);
void SetInsufficientSpaceDefaultSide(int);  int GetInsufficientSpaceDefaultSide() const;
void SetAutoCollapseOnInsufficientSpace(bool);  bool GetAutoCollapseOnInsufficientSpace() const;
ZSignal<int> CollapsedChanged;   // 0=expanded 1=first pane 2=second pane
void SetCollapseEnabled(bool);   bool IsCollapseEnabled() const;   void SetCollapseThreshold(float);
void CollapseFirst/CollapseSecond();   void Expand();   bool IsFirstCollapsed/IsSecondCollapsed() const;
void SetExpandButtonColors(Color,Color,Color);   void SetExpandButtonSize(float w,float h);
void SwitchToFirst/SwitchToSecond(bool animate = true);  void SwitchToPane(int side, bool animate = true);
void SetSwitchAnimationDuration(float);  void SetSwitchAnimationEasing(Easing);
bool IsSwitching() const;  float GetSwitchProgress() const;  int GetActivePane() const;
ZSignal<int> ActivePaneChanged;   // 1=first, 2=second
bool UseCache() const override { return false; }
```
- **Collapse (`v1.21.0`)**: drag the splitter to within `CollapseThreshold` (default 28px) of one side's edge → a translucent accent **overlay plus an arrow pointing in the collapse direction fades in ON TOP OF that pane's content** (the content is *not* changed yet); the pane actually collapses **on mouse release** (its size eases from the current value to 0). Once collapsed, a small button appears at that edge (rounded light grey + arrow pointing in the expand direction + hover easing); clicking it eases that side from 0 to its **minimum limit** (`SetMinFirst/MinSecond`, or back to the pre-collapse ratio if no minimum is set). The whole feature can be turned off with `SetCollapseEnabled(false)`.
- **Full-pane switch (v1.28.0)**: `SwitchToFirst/Second` slides from one fully expanded pane to the other (PageHost-style) even when both panes cannot fit at once; duration/easing are configurable, and the collapse state is committed with `ActivePaneChanged` when the transition finishes.
- When the available space cannot fit `minFirst + minSecond`, the expand button stays visible but is greyed out and non-interactive; it becomes enabled again when enough space returns.

###block_red_start
**Pitfall**

- `Orientation` naming is counter-intuitive (`Vertical` = vertical splitter, horizontal arrangement).
- the overlay is an internal `Overlay` **child element placed last** (the framework draws children in order), which is why it naturally ends up above both panes; do not try to paint such decorations from `SplitView::Draw` (the children would cover them).
###block_red_end

- **`Version`**: `v1.12.0`; NaN/Inf guard `v1.14.0`; collapse + expand button `v1.21.0`.

## Drawer (v1.25.0)

```cpp
enum class DrawerSide { Left, Right, Top, Bottom };
enum class DrawerMode { Overlay, Push, Permanent };
ZSignal<bool> OpenChanged;  ZSignal<> Opened, Closed, ScrimClicked;
void SetContent/SetPanel(std::shared_ptr<UIElement>);
void SetSide(DrawerSide);  void SetMode(DrawerMode);  void SetPanelSize(float);
void SetPanelPadding(const Thickness&);  void SetPanelCornerRadius(float);
void SetPanelBackgroundColor(Color);  void SetPanelBorderColor(Color);
void SetPanelShadow(bool);  void SetPanelShadowColor(Color);
void SetContentBorder(bool);  void SetContentBorderColor(Color);  void SetContentBorderCornerRadius(float);
void SetScrimColor(Color);  void SetScrimOpacity(float);  void SetModal(bool);
void SetDismissOnScrimClick(bool);  void SetDismissOnEscape(bool);
void SetFocusOnOpen(std::shared_ptr<UIElement>);
void SetAnimationDuration(float);  void SetAnimationEasing(Easing);
void Open/Close/Toggle();  bool IsOpen/IsAnimating() const;  float GetOpenProgress() const;
```
###block_list_start
###block_item_start
**Overlay**

Rounded scrim over content; dismiss with outside click or Esc. Good for navigation and filters.
###block_item_end
###block_item_start
**Push**

Content yields while the panel is open and participates in layout; good for list + detail side by side.
###block_item_end
###block_item_start
**Permanent**

Always open, no animation/scrim, `Close` ignored; good for persistent navigation or settings.
###block_item_end
###block_list_end

###block_green_start
**Recommended**

Use `Drawer` as the root layout or a `GridLayout` cell; Overlay for temporary content, Push when content should shrink, Permanent for long-lived navigation. Put panel content in `SetPanel` and the main content in `SetContent`.
###block_green_end

###block_orange_start

###block_red_start
**Pitfall**

- `SetContent` is the main content (covered/yielded by the drawer); `SetPanel` is the drawer panel. Putting panel content in `SetContent` skips the panel background, padding, rounded corners and shadow.
- `SetPanelSize` is the **outer** panel size; the default 16 px padding is subtracted from the panel content (e.g. outer `200` leaves `168` for content). Increase `SetPanelSize` or reduce `SetPanelPadding` when the panel needs more room.
- `Drawer` is a layout control and covers only its own arranged rect (the root layout or one `GridLayout` cell), **not** the window title bar/menu bar. Put it at the outermost level of the area you want to dim.
- `Open()` sets the target state and raises `OpenChanged` immediately; `Opened`/`Closed` fire only after the animation ends. `IsOpen()` returns the target state, not the current progress; use `IsAnimating()` / `GetOpenProgress()` during a transition.
- `Permanent` forces open, progress 1, no animation/scrim; `Close()` / `SetOpen(false)` are ignored. Switching back to Overlay/Push **does not auto-close**; call `Close()` explicitly.
- the scrim exists only in Overlay; `SetDismissOnScrimClick` / `ScrimClicked` work only with `SetModal(true)` and progress > 0. With `SetModal(false)`, clicks reach the content and `ScrimClicked` never fires.
- `SetScrimOpacity(0)` makes the scrim visually transparent but keeps modal hit-testing (clicks are still blocked); use `SetModal(false)` for click-through.
- `SetContentBorder` is drawn only in Overlay; Push/Permanent have no content border. The inner layers of `SetPanelShadow` are covered by the opaque panel background; only the outer shadow remains, and the border is painted last.
- Esc handling and `SetFocusOnOpen` require the `Drawer` to be attached to a `Window`; before attach, no Esc handler is registered and focus is not applied.
###block_red_end

- **`Version`**: `v1.25.0`.

## TabView

```cpp
struct Tab { std::shared_ptr<Label> label; std::shared_ptr<Page> page; bool closable; ... };
ZSignal<int> SelectionChanged;   ZSignal<int> TabCloseRequested;
int  AddTab(const std::wstring&, std::shared_ptr<UIElement> content=nullptr, bool closable=false, int id=-1);
int  AddTab(std::shared_ptr<Label>, ...);  int FindTabById(int) const;  int GetTabId(int) const;  bool RemoveTabById(int);
void InsertTab(int, ...);  void RemoveTab(int);  void ClearTabs();
void SetTabTitle(int, const std::wstring&);  void SetTabLabel(int, std::shared_ptr<Label>);  void SetTabContent(int, ...);
void SetSelectedIndex(int);  int GetSelectedIndex() const;
void SetTransitionDirection(PageHost::TransitionDirection);  void SetAutoTransitionDirection(bool);
```

###block_red_start
**Pitfall**

- content is hosted by an internal `PageHost`; `AddTab` auto-selects the first tab and raises `SelectionChanged`.
- `SetSelectedIndex`/switching is **asynchronous** (settles after the transition); `GetSelectedContent()`/index may be stale during it.
###block_red_end

- **`Version`**: `v1.11.0`; Label-based titles + `SetTabLabel` `v1.13.0`; locking `v1.15.0`.
Chapter 12

Containers & scrolling

ScrollViewer, ScrollBar, SplitView, Drawer, TabView

ScrollViewer

cpp
enum class ScrollBarVisibility { Auto, Always, Hidden };
ZSignal<float,float> ScrollChanged;
void SetContent(std::shared_ptr<UIElement>);
void SetVertical/HorizontalScrollEnabled(bool);
void SetVertical/HorizontalScrollBarVisibility(ScrollBarVisibility);
void SetScrollBarWidth(float);  void SetScrollWheelStep(float);  void SetAnimationSpeed(float);
void ScrollTo(float x,float y,bool animated=true);  void ScrollBy(...);
float GetScrollOffsetX/Y() const;

Pitfall

  • Hidden still allows programmatic/wheel scrolling.

ScrollBar (standalone, reusable)

cpp
std::function<void(float value, bool animate)> ValueChanged;
explicit ScrollBar(bool vertical);
void SetRange(float value, float maxValue, float viewportSize);   // host pushes each frame
void SetBarWidth(float);  void SetMinLength(float);  void SetHitExtra(float);
void SetColors(D2D1_COLOR_F thumb, D2D1_COLOR_F hoverThumb, D2D1_COLOR_F track);
void SetIdleDelay(float);  void SetAutoShrink(bool);  void MarkActive();
inline static float ShrunkWidthRatio;   // default 0.30

Pitfall

  • ValueChanged is a std::function (not ZSignal), signature (float, bool).
  • the idle-shrink countdown is not counted as an active animation — otherwise it put the whole window into animation mode and stopped data repaints from landing. Cost: idle shrink is lazy (triggered by the next frame).

SplitView

cpp
enum class Orientation { Vertical, Horizontal };   // Vertical = left/right panes + vertical splitter
ZSignal<float> SplitChanged;
void SetFirst/SetSecond(std::shared_ptr<UIElement>);
void SetSplitRatio(float);  void SetSplitterWidth(float);  void SetMinFirst/MinSecond(float);
void SetInsufficientSpaceDefaultSide(int);  int GetInsufficientSpaceDefaultSide() const;
void SetAutoCollapseOnInsufficientSpace(bool);  bool GetAutoCollapseOnInsufficientSpace() const;
ZSignal<int> CollapsedChanged;   // 0=expanded 1=first pane 2=second pane
void SetCollapseEnabled(bool);   bool IsCollapseEnabled() const;   void SetCollapseThreshold(float);
void CollapseFirst/CollapseSecond();   void Expand();   bool IsFirstCollapsed/IsSecondCollapsed() const;
void SetExpandButtonColors(Color,Color,Color);   void SetExpandButtonSize(float w,float h);
void SwitchToFirst/SwitchToSecond(bool animate = true);  void SwitchToPane(int side, bool animate = true);
void SetSwitchAnimationDuration(float);  void SetSwitchAnimationEasing(Easing);
bool IsSwitching() const;  float GetSwitchProgress() const;  int GetActivePane() const;
ZSignal<int> ActivePaneChanged;   // 1=first, 2=second
bool UseCache() const override { return false; }

Pitfall

  • Orientation naming is counter-intuitive (Vertical = vertical splitter, horizontal arrangement).
  • the overlay is an internal Overlay child element placed last (the framework draws children in order), which is why it naturally ends up above both panes; do not try to paint such decorations from SplitView::Draw (the children would cover them).

Drawer (v1.25.0)

cpp
enum class DrawerSide { Left, Right, Top, Bottom };
enum class DrawerMode { Overlay, Push, Permanent };
ZSignal<bool> OpenChanged;  ZSignal<> Opened, Closed, ScrimClicked;
void SetContent/SetPanel(std::shared_ptr<UIElement>);
void SetSide(DrawerSide);  void SetMode(DrawerMode);  void SetPanelSize(float);
void SetPanelPadding(const Thickness&);  void SetPanelCornerRadius(float);
void SetPanelBackgroundColor(Color);  void SetPanelBorderColor(Color);
void SetPanelShadow(bool);  void SetPanelShadowColor(Color);
void SetContentBorder(bool);  void SetContentBorderColor(Color);  void SetContentBorderCornerRadius(float);
void SetScrimColor(Color);  void SetScrimOpacity(float);  void SetModal(bool);
void SetDismissOnScrimClick(bool);  void SetDismissOnEscape(bool);
void SetFocusOnOpen(std::shared_ptr<UIElement>);
void SetAnimationDuration(float);  void SetAnimationEasing(Easing);
void Open/Close/Toggle();  bool IsOpen/IsAnimating() const;  float GetOpenProgress() const;

Overlay

Rounded scrim over content; dismiss with outside click or Esc. Good for navigation and filters.

Push

Content yields while the panel is open and participates in layout; good for list + detail side by side.

Permanent

Always open, no animation/scrim, Close ignored; good for persistent navigation or settings.

Recommended

Use Drawer as the root layout or a GridLayout cell; Overlay for temporary content, Push when content should shrink, Permanent for long-lived navigation. Put panel content in SetPanel and the main content in SetContent.

block_orange_start

Pitfall

  • SetContent is the main content (covered/yielded by the drawer); SetPanel is the drawer panel. Putting panel content in SetContent skips the panel background, padding, rounded corners and shadow.
  • SetPanelSize is the outer panel size; the default 16 px padding is subtracted from the panel content (e.g. outer 200 leaves 168 for content). Increase SetPanelSize or reduce SetPanelPadding when the panel needs more room.
  • Drawer is a layout control and covers only its own arranged rect (the root layout or one GridLayout cell), not the window title bar/menu bar. Put it at the outermost level of the area you want to dim.
  • Open() sets the target state and raises OpenChanged immediately; Opened/Closed fire only after the animation ends. IsOpen() returns the target state, not the current progress; use IsAnimating() / GetOpenProgress() during a transition.
  • Permanent forces open, progress 1, no animation/scrim; Close() / SetOpen(false) are ignored. Switching back to Overlay/Push does not auto-close; call Close() explicitly.
  • the scrim exists only in Overlay; SetDismissOnScrimClick / ScrimClicked work only with SetModal(true) and progress > 0. With SetModal(false), clicks reach the content and ScrimClicked never fires.
  • SetScrimOpacity(0) makes the scrim visually transparent but keeps modal hit-testing (clicks are still blocked); use SetModal(false) for click-through.
  • SetContentBorder is drawn only in Overlay; Push/Permanent have no content border. The inner layers of SetPanelShadow are covered by the opaque panel background; only the outer shadow remains, and the border is painted last.
  • Esc handling and SetFocusOnOpen require the Drawer to be attached to a Window; before attach, no Esc handler is registered and focus is not applied.

TabView

cpp
struct Tab { std::shared_ptr<Label> label; std::shared_ptr<Page> page; bool closable; ... };
ZSignal<int> SelectionChanged;   ZSignal<int> TabCloseRequested;
int  AddTab(const std::wstring&, std::shared_ptr<UIElement> content=nullptr, bool closable=false, int id=-1);
int  AddTab(std::shared_ptr<Label>, ...);  int FindTabById(int) const;  int GetTabId(int) const;  bool RemoveTabById(int);
void InsertTab(int, ...);  void RemoveTab(int);  void ClearTabs();
void SetTabTitle(int, const std::wstring&);  void SetTabLabel(int, std::shared_ptr<Label>);  void SetTabContent(int, ...);
void SetSelectedIndex(int);  int GetSelectedIndex() const;
void SetTransitionDirection(PageHost::TransitionDirection);  void SetAutoTransitionDirection(bool);

Pitfall

  • content is hosted by an internal PageHost; AddTab auto-selects the first tab and raises SelectionChanged.
  • SetSelectedIndex/switching is asynchronous (settles after the transition); GetSelectedContent()/index may be stale during it.
↑