内置图标字体说明

目标

为库层提供一套可直接使用的常用图标字体，优先覆盖通用 UI 场景，避免每个示例或应用重复打包菜单、搜索、关闭、刷新等基础图标。

这套机制有几个原则：

  • 直接内置到库里，应用侧不需要再配置 app_resource_config.json

  • 不依赖 UI Designer 的控件注册或元数据机制

  • 常用图标走库级公共字体，业务专用图标仍建议走应用资源管线

  • 图标以字体字形方式渲染，方便按文字颜色统一着色，缩放效果也更稳定

当前产物

  • 配置源：scripts/tools/build_in/material_symbols_common_icons.json

  • 中间文本：scripts/tools/build_in/material_symbols_common_text.txt

  • 生成脚本：scripts/tools/build_in/built_in_icon_font_gen.py

  • 总入口脚本：scripts/tools/build_in/built_in_font_gen.py

  • 头文件：src/resource/egui_icon_material_symbols.h

  • 字体资源：

    • src/resource/egui_res_font_material_symbols_common_16_4.c

    • src/resource/egui_res_font_material_symbols_common_20_4.c

    • src/resource/egui_res_font_material_symbols_common_24_4.c

使用方式

库头文件已经通过 src/resource/egui_resource.h 导出，因此正常包含 egui.h 即可使用。

#include "egui.h"

static egui_view_label_t icon_label;

egui_view_label_init(EGUI_VIEW_OF(&icon_label), core);
egui_view_label_set_font(EGUI_VIEW_OF(&icon_label), EGUI_FONT_ICON_MS_20);
egui_view_label_set_text(EGUI_VIEW_OF(&icon_label), EGUI_ICON_MS_SETTINGS);

目前提供三档常用尺寸：

  • EGUI_FONT_ICON_MS_16

  • EGUI_FONT_ICON_MS_20

  • EGUI_FONT_ICON_MS_24

图标内容通过宏直接取字符串，例如：

  • EGUI_ICON_MS_SEARCH

  • EGUI_ICON_MS_MENU

  • EGUI_ICON_MS_CLOSE

  • EGUI_ICON_MS_CHECK

  • EGUI_ICON_MS_SETTINGS

另外补了几个更适合直接当“符号字”使用的别名：

  • EGUI_ICON_MS_CHECK_MARK 对应 √

  • EGUI_ICON_MS_CROSS 对应 ×

  • EGUI_ICON_MS_HEART 对应 ♥

如果一个控件里既要显示普通文本，又要显示图标，建议：

  • 用两个独立 label 分开渲染

  • 或者继续走应用资源管线，按项目需要生成自己的混合字库

示例约定

库内部目前仍保留一层“按控件尺寸自动选择图标字体”的兼容逻辑，这样旧代码不至于立即失效。

但官方 example/ 示例现在统一约定：

  • 只要示例代码显式调用了图标相关 API，就同时显式调用对应的 *_set_icon_font()

  • 示例不再依赖控件内部的自动推断逻辑

  • 推荐优先使用 EGUI_FONT_ICON_MS_16、EGUI_FONT_ICON_MS_20、EGUI_FONT_ICON_MS_24

这样做的目的主要有两点：

  1. 示例行为更稳定，后续控件内部策略调整时不容易出现“看起来还能编译，但视觉效果悄悄变了”

  2. 示例代码本身能更直接地告诉用户“图标字符串”和“图标字体”是要成对考虑的

检查脚本

为防止示例回退到隐式推断，仓库增加了检查脚本：

  • scripts/checks/check_example_icon_font.py

这个脚本会扫描 example/ 下的 .c 文件（跳过 resource/），检查常见图标控件是否在设置图标内容后，也设置了对应的 icon font。

当前它已经接入：

  • scripts/release_check.py

也就是说，执行 release check 时，这条约定会自动校验；如果某个示例只设置了图标内容、没有设置 icon font，检查会直接报出具体文件和计数，便于回归修复。

重新生成

只更新内置图标字体：

python scripts/tools/build_in/built_in_icon_font_gen.py

同时更新 Montserrat 与内置图标字体：

python scripts/tools/build_in/built_in_font_gen.py

如果要扩充图标集合，流程是：

  1. 编辑 scripts/tools/build_in/material_symbols_common_icons.json

  2. 重新运行 python scripts/tools/build_in/built_in_icon_font_gen.py

  3. 检查 src/resource/egui_icon_material_symbols.h 和 3 个字体资源是否已更新

  4. 再执行一次常规构建验证

关于应用侧资源

这套内置图标字体适合做公共基础图标，不替代应用资源系统：

  • 业务 logo

  • 特定品牌图标

  • 只在单个应用里使用的私有图标

  • 需要和正文混排的定制字库

这类内容仍建议放在 example/{APP}/resource/src/ 下，通过现有资源生成流程管理。