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

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

Language

API reference / v1.29.1

Fonts & Icons

FontSpec, FontManager, Icon

Download 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 (singleton, text-layout cache)

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);   // ellipsized
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 must be called before any format/layout is created; it returns false when a cache or collection already exists. The manager holds a reference; menu paths that call CreateTextFormat directly still use system fonts.
  • The layout cache is bounded (400 entries, FIFO evicts ¼) and returns strong refs (ComPtr), safe during use.

Pitfall

  • returned layouts are shared read-only; do not call SetTextAlignment/SetLineSpacing/SetTrimming on them (the cache key would no longer match).
  • GetFormat's IDWriteTextFormat* is never evicted — do not mutate it.
  • the shared format returned by GetFormat sets ParagraphAlignment to CENTER. Do not draw multi-line custom text with it directly, or the text is vertically centred in a tall box and appears missing; use GetStyledLayout(..., vAlign) or your own format with NEAR.
  • Version: GetStyledLayout/global layout cache hardened in v1.10.1.

Icon (font glyphs)

enum class Icon : unsigned short { None=0x0000, Add=0xE710, Remove=0xE738, ..., Pin=0xE718, View=0xE890, ... };
inline const std::wstring& IconFontFamily();   // Segoe Fluent Icons → fallback Segoe MDL2 Assets
inline std::wstring IconGlyph(Icon);

Pitfall

  • the enum value is the font codepoint. Font fallback is probed once, statically; runtime font changes are not re-probed; a few Win11-only glyphs render as a box.
  • Version: Icon sunk into ZufyUIWidgets.h in v1.13.0; all Label-derived controls gained SetIcon.
View sourcedocs/src/API.en.md