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

主题系统

Theme(v1.19.0+)

下载 Markdown
// 语义色角色(按“角色”取色,而不是按控件)
enum class ThemeRole { Text, TextSecondary, TextDisabled, TextOnAccent,
    Surface, SurfaceAlt, SurfaceRaised, Backdrop, Overlay,
    Control, ControlHover, ControlPressed, ControlDisabled,
    Accent, AccentHover, AccentPressed,
    Border, Divider, FocusRing, Selection,
    ScrollTrack, ScrollThumb, ScrollThumbHover,
    Danger, Warning, Success, Info, Shadow, Count };
struct Theme { Color colors[(int)ThemeRole::Count]; FontSpec font, fontCaption, fontMono;
    float cornerRadius; bool isDark; std::wstring name;
    Color Get(ThemeRole) const;   void Set(ThemeRole, Color);
    static Theme Light();   static Theme Dark();   static Theme HighContrast(); };

// 应用级
void ThemeManager::SetAppTheme(const Theme&);   void ThemeManager::SetLight/DarkAppTheme();
Theme& ThemeManager::AppTheme();   bool ThemeManager::IsDark();
// 跟随系统(注册表 AppsUseLightTheme + DWM AccentColor;WM_SETTINGCHANGE 等自动重解析)
void ThemeManager::SetFollowSystem(bool);   bool ThemeManager::IsFollowingSystem();
bool ThemeManager::SystemPrefersDark();   Color ThemeManager::SystemAccent();   Theme ThemeManager::SystemTheme();
// 测试钩子:模拟系统主题(绕过注册表)
void ThemeManager::DebugForceSystemTheme(bool enable, bool dark, bool highContrast);
// 色差重映射:任意硬编码色 → 主题色(精确表,未命中原样返回、保留 alpha)
void ThemeManager::SetColorMap(std::unordered_map<uint32_t, Color>);   Color ThemeManager::Map(Color);
// 钩子注册:返回 RAII HookHandle(析构自动断开);库内部固定钩子用 RegisterHookPermanent
HookHandle ThemeManager::RegisterHook(std::function<void(const Theme&)>);
HookHandle ThemeManager::RegisterSubtreeApplier(std::function<void(UIElement*, const Theme&)>);
// 调试:主题名 + 各 Role 的 AARRGGBB(调试通道命令 23 GetTheme)
std::wstring ThemeManager::Dump();

// 窗口级
void Window::SetTheme(const Theme&);   const Theme& Window::GetTheme();
void Window::SetUseAppTheme(bool = true);   bool Window::IsUsingAppTheme();   void Window::RefreshTheme();
ZSignal<Window*> UIZSignals::ThemeChanged;   // nullptr=应用级
ZSignal<Window*> UIZSignals::ThemeReapply;   // 页面/标签切换后重套可见子树
  • 取色优先级:实例显式设色 > 窗口主题 > 应用主题。控件只要被显式调用过任何 Set*Color,就标记为“用户设色”,主题切换不再覆盖它;其余控件跟随主题。

易错

  • Backdrop 是窗口/背景基色(浅色白、深色黑);SetBackdrop/SetBackgroundColor 显式指定 tint 后主题不再改它。
  • 版本:v1.19.0 引入;窗口周边(标题栏三件套)跟随系统主题而非窗口主题;WM_SETTINGCHANGE/WM_THEMECHANGED/WM_DWMCOLORIZATIONCOLORCHANGED/WM_SYSCOLORCHANGE 自动重解析。
查看源文件docs/src/API.md