## FontSpec
```cpp
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)
```cpp
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.
###block_red_start
**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`.
###block_red_end
- **`Version`**: `GetStyledLayout`/global layout cache hardened in `v1.10.1`.
## Icon (font glyphs)
```cpp
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);
```
###block_red_start
**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.
###block_red_end
- **`Version`**: `Icon` sunk into `ZufyUIWidgets.h` in `v1.13.0`; all `Label`-derived controls gained `SetIcon`.Fonts & Icons
FontSpec, FontManager, Icon
FontSpec
cpp
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)
cpp
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;
SetAppFontCollectionmust be called before any format/layout is created; it returnsfalsewhen a cache or collection already exists. The manager holds a reference; menu paths that callCreateTextFormatdirectly 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/SetTrimmingon them (the cache key would no longer match). GetFormat'sIDWriteTextFormat*is never evicted — do not mutate it.- the shared format returned by
GetFormatsetsParagraphAlignmenttoCENTER. Do not draw multi-line custom text with it directly, or the text is vertically centred in a tall box and appears missing; useGetStyledLayout(..., vAlign)or your own format withNEAR.
Version:GetStyledLayout/global layout cache hardened inv1.10.1.
Icon (font glyphs)
cpp
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:Iconsunk intoZufyUIWidgets.hinv1.13.0; allLabel-derived controls gainedSetIcon.