ScrollViewer
enum class ScrollBarVisibility { Auto, Always, Hidden };
ZSignal<float,float> ScrollChanged; // (offsetX, offsetY),动画中也发
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;
易错
Hidden仍允许程序化/滚轮滚动(只是不显示条)。
版本:v1.18.0起ScrollViewer::UseCache()==false(内容常变/可滚动,缓存无益且占大位图)。
ScrollBar(独立可复用)
std::function<void(float value, bool animate)> ValueChanged;
explicit ScrollBar(bool vertical);
void SetRange(float value, float maxValue, float viewportSize); // 宿主每帧推入
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; // 默认 0.30
- 拖动 →
animate=false(跟手);点轨道 →animate=true。悬停扩张 + 空闲缩小;宿主用ShrunkWidthRatio预留槽位。
易错
ValueChanged是std::function(不是ZSignal),签名(float, bool)。ShrinkTarget的“空闲等待缩小”倒计时不再算作活跃动画——否则会把整窗顶进动画模式导致数据重绘不落屏。代价:空闲缩小变惰性(到点后由下一帧触发)。
版本:v1.11.0起独立复用;ShrunkWidthRatiov1.13.0。
SplitView
enum class Orientation { Vertical, Horizontal }; // Vertical = 左右两栏 + 竖直分隔条
ZSignal<float> SplitChanged; // 新比例 0..1
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=未折叠 1=第一栏 2=第二栏
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; }
- 折叠(
v1.21.0):把分隔条拖到距某侧边缘CollapseThreshold(默认 28px)内 → 该侧内容上方浮出半透明强调色覆盖层 + 指向折叠方向的箭头(alpha 渐入渐出);此时不改内容,松手才真正折叠(该侧尺寸带缓动从当前值变为 0)。折叠后该侧边缘出现小按钮(圆角浅灰 + 指向展开方向的箭头 + 悬停缓动),点击后该侧尺寸带缓动从 0 变为最小极限值(SetMinFirst/MinSecond;未设则回到折叠前比例)。整个功能可SetCollapseEnabled(false)关闭。 - 全屏面板切换(v1.28.0):
SwitchToFirst/Second从一个完整面板滑动过渡到另一个完整面板(类似 PageHost),不依赖两面板同时容得下;方向/时长/缓动可配置,结束后更新折叠状态并发出ActivePaneChanged。 - 当剩余空间连
minFirst + minSecond都放不下时,展开按钮仍然显示,但会变灰、不可悬停也不可点击;空间恢复后自动重新启用。
易错
Orientation命名反直觉(Vertical指竖直分隔条、水平排列两栏)。- 覆盖层与本控件内部的
Overlay子元素有关——它是最后一个子元素(框架按子元素顺序绘制),所以天生画在两栏内容之上;不要试图在SplitView::Draw里画这类装饰(会被内容盖住)。
版本:v1.12.0;NaN/Inf 守卫v1.14.0;折叠/小按钮v1.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
圆角遮罩覆盖内容;点外部或 Esc 关闭。适合导航、筛选等临时面板。
Push
打开时内容让位,面板参与布局;适合需要同时查看列表和详情的场景。
Permanent
常驻侧栏,无动画/遮罩,Close 无效;适合固定导航或设置入口。
推荐
优先把
Drawer当根布局或放进GridLayout的 cell;普通内容放 Overlay,需要内容缩窄时用 Push,长期导航用 Permanent。面板内容用SetPanel,主内容用SetContent。
易错
SetContent是主内容(会被抽屉遮住/让位),SetPanel才是抽屉面板。把面板内容塞进SetContent不会得到面板背景、内边距、圆角和阴影。SetPanelSize是面板外框尺寸;默认 16px 内边距会先从面板内容中扣除(例如200的外宽只剩168给内容)。面板内容需要更宽时,调大SetPanelSize或减小SetPanelPadding。Drawer是布局控件,只覆盖它自己的 arranged rect(根布局或某个GridLayoutcell),不覆盖窗口标题栏/菜单栏;要压暗整个内容区就放在对应区域的最外层。Open()立即把目标状态设为打开并触发OpenChanged;Opened/Closed要等动画结束才触发。IsOpen()返回目标状态,不是当前进度;动画中请用IsAnimating()/GetOpenProgress()。Permanent模式会强制打开、进度直接为 1、无动画/遮罩;Close()/SetOpen(false)被忽略。从 Permanent 切回 Overlay/Push 不会自动关闭,需要再调Close()。- Scrim 只在 Overlay 模式存在;
SetDismissOnScrimClick/ScrimClicked只在SetModal(true)且进度 > 0 时生效。SetModal(false)后点击会落到内容上,ScrimClicked不会触发。SetScrimOpacity(0)只是把遮罩画成透明,模态命中仍在(仍拦截点击);要穿透请用SetModal(false)。SetContentBorder只在 Overlay 模式绘制;Push/Permanent 没有内容边框。SetPanelShadow的内层会被不透明面板背景覆盖,只有外侧阴影可见,边框最后绘制。- Esc 拦截和
SetFocusOnOpen都要求Drawer已挂到Window;还没 attach 时不会注册 Esc,也不会执行聚焦。
版本: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, ...); void SetTabLabel(int, std::shared_ptr<Label>); void SetTabContent(int, ...);
void SetSelectedIndex(int); int GetSelectedIndex() const;
void SetTransitionDirection(PageHost::TransitionDirection); void SetAutoTransitionDirection(bool);
易错
- 内容由内部
PageHost承载;AddTab首个页签会自动选中并触发SelectionChanged。SetSelectedIndex/切换是异步的(过渡动画结束才定),GetSelectedContent()/索引在动画期间可能仍是旧值。
版本:v1.11.0;Label 化标题 +SetTabLabelv1.13.0;加锁v1.15.0。