## 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`.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
Hiddenstill allows programmatic/wheel scrolling.
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 viaShrunkWidthRatio.
Pitfall
ValueChangedis astd::function(notZSignal), 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).
Version: reusable sincev1.11.0;ShrunkWidthRatiov1.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 withinCollapseThreshold(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 withSetCollapseEnabled(false). - Full-pane switch (v1.28.0):
SwitchToFirst/Secondslides 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 withActivePaneChangedwhen 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.
Pitfall
Orientationnaming is counter-intuitive (Vertical= vertical splitter, horizontal arrangement).- the overlay is an internal
Overlaychild 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 fromSplitView::Draw(the children would cover them).
Version:v1.12.0; NaN/Inf guardv1.14.0; collapse + expand buttonv1.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;
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
SetContentis the main content (covered/yielded by the drawer);SetPanelis the drawer panel. Putting panel content inSetContentskips the panel background, padding, rounded corners and shadow.SetPanelSizeis the outer panel size; the default 16 px padding is subtracted from the panel content (e.g. outer200leaves168for content). IncreaseSetPanelSizeor reduceSetPanelPaddingwhen the panel needs more room.Draweris a layout control and covers only its own arranged rect (the root layout or oneGridLayoutcell), 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 raisesOpenChangedimmediately;Opened/Closedfire only after the animation ends.IsOpen()returns the target state, not the current progress; useIsAnimating()/GetOpenProgress()during a transition.Permanentforces open, progress 1, no animation/scrim;Close()/SetOpen(false)are ignored. Switching back to Overlay/Push does not auto-close; callClose()explicitly.- the scrim exists only in Overlay;
SetDismissOnScrimClick/ScrimClickedwork only withSetModal(true)and progress > 0. WithSetModal(false), clicks reach the content andScrimClickednever fires. SetScrimOpacity(0)makes the scrim visually transparent but keeps modal hit-testing (clicks are still blocked); useSetModal(false)for click-through.SetContentBorderis drawn only in Overlay; Push/Permanent have no content border. The inner layers ofSetPanelShadoware covered by the opaque panel background; only the outer shadow remains, and the border is painted last.- Esc handling and
SetFocusOnOpenrequire theDrawerto be attached to aWindow; before attach, no Esc handler is registered and focus is not applied.
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);
Pitfall
- content is hosted by an internal
PageHost;AddTabauto-selects the first tab and raisesSelectionChanged. SetSelectedIndex/switching is asynchronous (settles after the transition);GetSelectedContent()/index may be stale during it.
Version:v1.11.0; Label-based titles +SetTabLabelv1.13.0; lockingv1.15.0.