ScrollViewer
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)
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
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)
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
Draweras the root layout or aGridLayoutcell; Overlay for temporary content, Push when content should shrink, Permanent for long-lived navigation. Put panel content inSetPaneland the main content inSetContent.
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
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.