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

字体与图标

FontSpec、FontManager、Icon

下载 Markdown

FontSpec

struct FontSpec {
    std::wstring familyName = L"Segoe UI";
    float size = 14.0f;
    DWRITE_FONT_WEIGHT weight = DWRITE_FONT_WEIGHT_NORMAL;
    DWRITE_FONT_STYLE  style  = DWRITE_FONT_STYLE_NORMAL;
    DWRITE_FONT_STRETCH stretch = DWRITE_FONT_STRETCH_NORMAL;
    std::wstring locale = L"en-us";
    bool operator==/!=(...) const;
};

FontManager(单例,文本布局缓存)

static FontManager& Instance();
IDWriteFactory* GetFactory();
IDWriteTextFormat* GetFormat(const FontSpec&);
bool SetAppFontCollection(IDWriteFontCollection*);   // install once, before formats
ComPtr<IDWriteTextLayout> GetRawLayout(text, fmt, maxW, maxH, noWrap);
ComPtr<IDWriteTextLayout> GetDisplayLayout(origText, fmt, maxW, maxH, noWrap);   // 带省略号
ComPtr<IDWriteTextLayout> GetStyledLayout(text, fmt, w, h, noWrap, hAlign, vAlign, lineSpacing, maxLines);
ComPtr<IDWriteTextLayout> GetStyledDisplayLayout(...);
void CacheDisplayLayout(...); void CacheStyledDisplayLayout(...);
void SetGlobalFont(const FontSpec&);
ZSignal<> GlobalFontChanged;
  • SetAppFontCollection 必须在任何 format/layout 创建之前调用;已有缓存或已安装时返回 false。内部持有集合引用;菜单直接 CreateTextFormat 的路径仍用系统字体。
  • 布局缓存有上限(400 条,FIFO 淘汰 ¼);返回强引用(ComPtr),调用期间不会被淘汰。

易错

  • 返回的 layout 是共享只读对象,不要对它 SetTextAlignment/SetLineSpacing/SetTrimming——缓存 key 会与对象不一致。
  • GetFormat 返回的 IDWriteTextFormat* 永不淘汰,请勿修改它。
  • GetFormat 的共享 format 把 ParagraphAlignment 设成了 CENTER。不要直接拿它画多行自绘文本,否则会被垂直居中到高盒外(看起来“没字”);用 GetStyledLayout(..., vAlign) 或自建 format 并设 NEAR。
  • 版本:GetStyledLayout 与全局布局缓存在 v1.10.1 强化;有界缓存/强引用契约在 v1.15.0 前后定型。

图标 Icon(字体字形)

enum class Icon : unsigned short { None=0x0000, Add=0xE710, Remove=0xE738, ..., Pin=0xE718, View=0xE890, ... };
inline const std::wstring& IconFontFamily();   // Segoe Fluent Icons → 回退 Segoe MDL2 Assets
inline std::wstring IconGlyph(Icon);           // 码点 → 单字宽字符串

易错

  • 枚举值就是字体码点(无独立映射表)。字体回退只在首次静态探测,运行期换系统字体不会重探;个别 Win11 专有字形在两版字体里缺失会显示方框。
  • 版本:v1.13.0 起 Icon 下沉到 ZufyUIWidgets.h,所有 Label 派生控件获得 SetIcon。
查看源文件docs/src/API.md