ZZufyUI文档首页DocumentationДокументацияDokumentationDocumentationDocumentación

正在准备文档Preparing your docsПодготовка документацииDokumentation wird geladenPréparation de la documentationPreparando la documentación

从这里开始 · 支持全文搜索

框架概览

轻量到几 MB,快到原生合成。 纯头文件、零第三方依赖的 C++20 Windows 自绘 UI 框架,直接构建在 Direct2D 1.1 + DirectComposition 之上。 - 没有 Qt 的打包包袱,没有 Electron 的内存税。 几个头文件,include 即用;应用工程不链

易错点

> 这份文件把散落在代码注释、HANDOFF.md、TODO.md 里的“坑”集中到一处。接手/使用前先扫一遍。 > 优先级:易错 = 违反必踩;注意 = 契约/限制,违反易出问题;约定 = 库的取向;不要 = 明确不做。 --- 1. 链式构造 DSL(ZufyUIDsl.h) | | 状态 |

参考总览

> 本文档覆盖 ZufyUI 框架的全部公开 API,按“使用分类”组织(不是按代码/头文件顺序)。 > 配套阅读:[项目说明与构建](https://github.com/zhc9968/ZufyUI/blob/master/README.md)。 > 阅读方式:本文不是“签名清单”,而是按“它是

约定

颜色与标记 - 红色块:易错——真实踩坑、反直觉行为、会崩溃/UAF/竞争的用法,优先看。 - 橙色块:注意——线程、生命周期、绘制顺序等契约;不一定是错误,但违反后容易出问题。 - 绿色块:推荐——推荐写法、所有权模型、最佳实践。 - 普通项目符号表示普通语义、默认值或版本变化,不代表没有风险。

快速开始

最小程序 cpp include "ZufyUI.h" include "ZufyUIWidgets.h" using namespace ZufyUI; int APIENTRY wWinMain(HINSTANCE, HINSTANCE, LPWSTR, int) { // Windows 子系

基础类型

Color cpp struct Color { float r, g, b, a; // 分量范围 [0,1],不是 0..255 Color(float r=0, float g=0, float b=0, float a=1.0f); static Color FromArgb(uint8t

事件与信号

何时用信号 - 控件对外通知(点击、选中、值变化)用内置 ZSignal。 - 自定义控件对外事件:自己声明 ZSignal 成员并 Fire。 ConnectionThread cpp enum class ConnectionThread { CurrentThread, NewThread,

语言

API 参考 / v1.29.1

窗口

Window(创建、显示、背景、标题栏、任务栏、DPI、帧率)

下载 Markdown

嵌套公开类型

struct BackgroundParams { float blurAmount=30, saturation=1; D2D1_COLOR_F tint, luminosity; float noiseOpacity=0.02f; };
enum class AcrylicPreset { Legacy, Luminosity, Base, Thin };
struct CaptionMetrics { bool valid; float rightMargin, top, height, width; };
enum class TaskbarProgress { None=0, Indeterminate=1, Normal=2, Error=4, Paused=8 };
enum class ThumbButtonId : UINT { Play=0, Pause=1, Prev=2, Next=3, MaxId=4 };
struct JumpListItem { std::wstring title, arguments, target, iconPath; int iconIndex=0; };
enum class ActivateMode { Raise, Activate, Foreground, All };
enum class OwnedMinimizePolicy { None, Hide, DisableMinimize };

静态配置

inline static Backdrop DefaultBackdrop = Backdrop::None;
inline static DWORD     DefaultBackdropColor = 0xFFFFFFFF;   // 默认纯白,v1.17.0
static void SetDefaultBackdrop(Backdrop, DWORD tint = 0);
static void SetBackgroundParams(Backdrop which, const BackgroundParams&);
static void SetBackgroundParams(Backdrop which, AcrylicPreset);
static void SetDefaultFrameRateLimit(int fps);   // v1.14.2
static void SetDefaultAppIcon(HICON big, HICON small = nullptr);
static void SetProcessAppUserModelID(const std::wstring& id);

渲染驱动(v1.27.0)

enum class RenderDriver { Auto, Hardware, WARP, Unknown };
void SetRenderDriver(RenderDriver);
RenderDriver GetRequestedRenderDriver();
RenderDriver GetActiveRenderDriver();
bool IsRenderDriverReady();
std::wstring GetRenderDeviceName();
  • 必须在第一次 Window::Create / D3D 设备创建之前调用;设备创建后再调用只记录错误,不会切换。
  • Auto:硬件优先,失败回退 WARP;Hardware:强制硬件,失败即不可用;WARP:强制软件光栅化。
  • GetActiveRenderDriver() 返回实际创建成功的驱动,GetRenderDeviceName() 返回 DXGI 适配器名称。
  • 注意:WARP 只改变 ZufyUI 自己的 D3D11/D2D 内容渲染;WinRT Compositor、DWM 合成和 Acrylic 效果仍可能使用 GPU。Win10 无 GPU 虚拟机中 DWM 整体软件化时,GPU 才接近 0。
  • demo 支持 --warp / --gpu,首页底部也有重启进程的切换按钮。
  • 版本:v1.27.0。

创建 / 生命周期

bool Create(int w, int h, const std::wstring& title, int x=CW_USEDEFAULT, int y=CW_USEDEFAULT);
bool IsValid() const;   HWND GetHwnd() const;   int GetId() const;
void Show(); void ShowNoActivate(); void Hide(); void Raise(); void Close();
void Run();  int RunModal(Window* owner = nullptr);
void SetInputBlocked(bool);  bool IsInputBlocked() const;
std::unique_lock<std::recursive_mutex> LockRender();  void RenderNowSync();
void SetNonBlockingPresent(bool);   bool GetNonBlockingPresent() const;
void SetDisplayFramePacing(bool);   bool GetDisplayFramePacing() const;
double GetDisplayRefreshHz() const;
enum class PresentationState { Hidden, Opening, Open, Closing, Closed };
void SetTransitionDurations(int enterMs, int exitMs);
PresentationState GetPresentationState() const;  float GetPresentationProgress() const;  bool IsTransitionActive() const;
inline static std::function<void(Window&)> DefaultWindowSetup;
  • SetNonBlockingPresent / SetDisplayFramePacing 默认关,菜单默认开;SetDisplayFramePacing 仅在非阻塞 Present 下生效。GetDisplayRefreshHz() 返回当前显示器刷新率(未知时为 60)。

易错

  • Create 不自动 Show(v1.8.0 起)。RunModal 用 EnableWindow(FALSE) 禁用 owner、不使用 IsDialogMessage。

临时键处理器(v1.25.0)

using KeyHandler = std::function<bool(int)>;
int  AddKeyHandler(KeyHandler handler);
void RemoveKeyHandler(int id);
  • 在 OnWindowKeyDown 之后、焦点元素之前调用;返回 true 表示已处理。
  • 按注册顺序调用;AddKeyHandler 返回 id,RemoveKeyHandler(id) 注销。
  • 供抽屉/浮层临时拦截 Esc;组件关闭/detach/析构时必须移除。
  • 版本:v1.25.0。

易错

  • 每次按键会先复制一份 handler 快照;在回调里 RemoveKeyHandler 不会取消当前这一轮,已经被移除的 handler 仍可能再执行一次。
  • 返回 true 会吞掉按键,焦点元素和后续 handler 都收不到;不要无条件拦截 Tab/Enter/Esc。
  • handler 通常捕获裸 this;宿主必须在销毁前移除,否则窗口还活着时会回调悬空对象(Drawer 已自动处理)。
  • 键处理器在 UI 线程调用;不要在 handler 里长时间阻塞,也不要在其他线程增删。

三种建窗方式(选哪个)

方式 代码 所有权 消息循环 适用场景
栈上值 Window w; w.Create(...); w.Show(); app.Run(); 你自己(作用域) 共享 Run() 单一主窗口、生命周期简单
shared_ptr auto w = app.CreateWindow(...); w->Show(); app.Run(); shared_ptr 引用计数 共享 Run() 多窗口、需动态创建/销毁
模态 int r = w->RunModal(owner); 同 shared_ptr 嵌套循环,阻塞至关闭 对话框 / 确认框

易错

  • Window 不可拷贝;栈上用法要保证它活得比 Run() 久(否则消息循环仍在引用已析构窗口)。
  • Application::CreateWindow 返回的 shared_ptr 就是所有权——丢掉指针窗口就销毁;Create 也不会自动 Show。

所有权 / 多窗口 / 尺寸

void SetOwner(Window*);  Window* GetOwner() const;
std::vector<Window*> GetOwnedWindows() const;
void HideOwnedWindows(); void ShowOwnedWindows();
void SetPosition(int x, int y);  void SetSize(int w, int h);   // DIP
void SetMinSize(int w, int h);
void SetOwnedMinimizePolicy(OwnedMinimizePolicy);

易错

  • SetOwner 要在 Create 之前,否则会自带任务栏按钮、且不随 owner 最小化。
  • SetMinSize 会覆盖基于内容的最小尺寸计算。含长文本/图表的窗口若不设,最小尺寸可能被内容撑大(内部用 rootElement->Measure(Size(0,0)),宽度 0 时换行 Label 会按整行宽度上报)。含图表的调试器窗口已显式 SetMinSize。

根内容 / 捕获

void SetRootLayout(std::shared_ptr<Layout>);
std::shared_ptr<ColumnBox> GetRootColumnBox() const;   // 默认根:ColumnBox margin(20) spacing 10
void SetContextMenu(std::shared_ptr<Menu>);  void CloseContextMenu();
UIElement* HitTestElement(float x, float y);
void CollectDragRegions();  bool PointInDragRegion(float,float) const;
void MarkRepaint(UIElement*);   // 标脏;只记录,不定帧(帧由定时器/动画驱动)
float GetDpiScale() const;  float GetClientWidthDip/HeightDip() const;

易错

  • MarkRepaint 存裸指针,元素析构会自动注销;不要跨销毁持有外部指针。
  • RequestRepaint() → MarkRepaint 不会主动排一帧。帧由 16ms WM_TIMER(忙时)或动画续帧驱动。历史教训:曾在这里强制排帧,导致“每次重绘都出一帧”的持续重渲染(严重卡顿),已回退。

外观 / 背景

void SetBackdrop(Backdrop, DWORD tint=0);  Backdrop GetBackdrop() const;
void SetBackgroundColor(Color);            // 叠加在背景(空/亚克力/云母)之上的颜色
void SetContentOpacity(float opacity);     // 弹窗淡入
void SetTitleBarColors(COLORREF caption, COLORREF text, COLORREF border);
void SetResizable(bool);   void SetTitle(const std::wstring&);
void SetSuspendAnimationsWhileResizing(bool);   bool GetSuspendAnimationsWhileResizing() const;
  • 背景是自绘:Acrylic = 宿主背景 + 自带效果链;Mica = 缓存壁纸层。改参数用 SetBackgroundParams 或 UIZSignals::ReloadAcrylic。
  • 窗口圆角不再提供公开 API:Win10 保持系统直角以保留 DWM 边框/阴影,Win11 跟随系统圆角。需要自定义圆角时请自行调用 Win32 DWM API,并自行处理 Win10/Snap 的边框阴影风险。
  • DefaultBackdropColor 默认纯白(v1.17.0)。SetContentOpacity 需合成后端就绪。
  • 版本:四层参数 v1.8.1;SetContentOpacity v1.9.6。

自定义标题栏

void SetCustomTitleBar(std::shared_ptr<UIElement>);  std::shared_ptr<UIElement> GetCustomTitleBar() const;
bool HasCustomTitleBar() const;   void SetTitleBarVisible(bool);
CaptionMetrics QueryCaptionMetrics() const;
void Minimize(); void Maximize(); void Restore(); void MaximizeRestore();
bool IsMaximizedWindow() const;   void BeginSystemDrag();
// 顶部菜单栏 / 底部状态栏(窗口级 chrome,v1.19.2)
void SetMenuBar(std::shared_ptr<UIElement>);    std::shared_ptr<UIElement> GetMenuBar() const;
void SetStatusBar(std::shared_ptr<UIElement>);  std::shared_ptr<UIElement> GetStatusBar() const;
void SetMenuBarInTitleBar(bool on = true);      bool IsMenuBarInTitleBar() const;
void SetShowTitleText(bool on);                 bool IsShowTitleText() const;
  • 菜单栏默认叠在自定义标题栏上(让开左侧图标、右侧系统按钮);此时标题文字默认隐藏(与菜单互斥,避免重叠)。SetShowTitleText(true) → 显示标题、菜单栏自动移到标题栏下方的客户区顶部;SetMenuBarInTitleBar(false) 强制放到客户区顶部。状态栏固定贴底,根内容高度相应收缩。

易错

  • 自定义标题栏不参与布局——Window 把它放 (0,0),并把根内容下移它测量出的高度。别手动 AddChild。
  • 版本:v1.7.0 起;CaptionButton::Kind::Pin = v1.17.0。

任务栏 / 缩略图 / 跳转列表

void SetTaskbarProgress(TaskbarProgress, ULONGLONG done=0, ULONGLONG total=0);  void ClearTaskbarProgress();
void SetTaskbarOverlayIcon(HICON, const std::wstring& = L"");  void ClearTaskbarOverlayIcon();
ZSignal<ThumbButtonId> ThumbButtonClicked;
void SetThumbButtons(...);   void UpdateThumbButton(ThumbButtonId, bool enabled);
void SetJumpList(...);  void Flash(int times=5, bool alsoTaskbar=true);  void FlashUntilForeground();
void SetAppUserModelID(const std::wstring&);
  • 版本:均 v1.9.6。

DPI

  • 进程级 Per-Monitor-v2 在静态初始化设置(回退 SetProcessDPIAware)。
  • WM_DPICHANGED 会重建整条渲染链并清空所有缓存。

易错

  • 元素缓存会在 DPI 变更时被清;但子布局不需要你手动重测。

无障碍 / 信号

void SetAccessibilityEnabled(bool);   bool IsAccessibilityEnabled() const;   // 默认开,v1.17.0
UIElement* GetFocusedElement/HoveredElement/PressedElement() const;
void FocusElement(UIElement*);
ZSignal<> Activated, Deactivated;   ZSignal<bool*> Closing;   ZSignal<> Closed;
ZSignal<float, float> SizeChanged;   // client size in DIP
ZSignal<float> DpiChanged;           // DPI scale (96 = 1.0)
ZSignal<> BackdropUnsupported, DeviceLost;   ZSignal<HRESULT> RenderingError;
std::shared_ptr<Timer> CreateTimer(int intervalMs = 1000);
  • SizeChanged 在客户端 DIP 尺寸实际变化时触发(最小化时不触发);初始尺寸用 GetClientWidthDip/HeightDip() 读取。DpiChanged 在 DPI 变化时先触发,即使后续设备重建失败;DIP 客户端尺寸变化时会再触发 SizeChanged。

易错

  • Closing 里把 *cancel = true 可取消关闭。Closing 的参数是 bool*(不是引用)。

弹窗窗口行为(v1.27.3)

enum class Placement { SystemDefault, CenterOwner, CenterScreen };
enum class MoveBounds { Unrestricted, OwnerClient, MonitorWorkArea };
enum class CloseReason { Programmatic, Caption, Escape, System, Forced };
void SetPlacement(Placement);   Placement GetPlacement() const;
void CenterOnOwner();   void CenterOnScreen();
void SetMovable(bool);   bool IsMovable() const;
void SetCloseEnabled(bool);   bool IsCloseEnabled() const;
void SetCloseOnEscape(bool);   bool GetCloseOnEscape() const;
void SetFollowOwner(bool);   bool GetFollowOwner() const;
void SetMoveBounds(MoveBounds);   MoveBounds GetMoveBounds() const;
void RequestClose(CloseReason = CloseReason::Programmatic);   void ForceClose();
ZSignal<> Opening, Opened, BehaviorChanged;
ZSignal<CloseReason, bool*> CloseRequested;   ZSignal<CloseReason> CloseAccepted, CloseCancelled;
  • CenterOwner 仅在未显式设置初始位置时生效;SetPosition 会标记为显式位置。
  • FollowOwner 让 owned 子窗口在 owner 移动时跟随;MoveBounds 同时用于拖动和屏幕/工作区裁剪。
  • 关闭优先级:CloseRequested 可拦截;ForceClose 跳过拦截但仍走正常 HWND 清理。
  • 首次 Show 前会推进一帧,减少弹窗首帧空白。
查看源文件docs/src/API.md