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。