raygui Terminal 风格接入指南:Mecha 字体驱动的终端复古 UI 主题与五种加载方式

原创2026-10-14 12:42:521,742 阅读
文章标签:UI组件桌面应用

raygui Terminal 风格接入指南:Mecha 字体驱动的终端复古 UI 主题与五种加载方式

raygui 内置的 Terminal 风格(styles/terminal/README.md)以暗色背景、荧光绿文字还原经典命令行终端观感,并配套自定义字体 "Mecha"。本文围绕该风格的使用展开:先介绍其配色与文件清单,再逐一讲解二进制 .rgs、文本 .rgs、嵌入 .h、样式表 PNG 等五种接入方式,并结合 src/raygui.h 的 GuiLoadStyle() / GuiLoadStyleFromMemory() 实现剖析 rgs 文件格式与字体数据压缩原理,最后给出字体信息与版本注意事项。读完即可在自己的 raygui 应用中快速启用 Terminal 风格,并理解不同接入方式的取舍。

raygui Terminal 风格完整界面截图,展示深色终端配色下的各类控件

风格概览:暗底亮绿的终端美学

Terminal 风格的定位十分明确:"启动你的终端,敲入命令,感受数据流动的连接感"。它采用典型的终端配色——极暗背景(0x0c1505,接近纯黑的墨绿色)、荧光绿文字(0x38f620)与深绿/浅绿交织的边框,控件在正常、聚焦、按下、禁用四种状态下呈现不同的绿色阶调,视觉上高度还原字符终端界面,适合命令行工具、调试面板、日志查看器等工具类应用。

下面是该风格的颜色表,展示了默认控件在各状态下的完整配色:

raygui Terminal 风格控件颜色表,横排展示默认控件在不同状态下的配色

提供的文件清单

该风格的官方说明提供了多种接入方式,开发者可按项目需求选择其一。原文档文件清单如下(各文件位于 styles/terminal 目录):

文件名称 说明
style_terminal.rgs 二进制样式文件(raygui 4.0 格式),字体数据已压缩(recs、glyphs)
style_terminal.rgs.txt 文本样式文件,不含字体数据,需要外部提供字体
style_terminal.old.rgs 二进制样式文件(raygui 3.x 格式),字体数据未压缩(recs、glyphs)
style_terminal.h 可嵌入代码的样式文件,自包含,含字体数据
style_terminal.png 样式表图片,内含 rGSf 数据块,携带二进制 rgs 文件数据

说明:以上清单以原 README 声明为准。以当前仓库实际内容核对,styles/terminal 目录下实际提供 style_terminal.rgs、style_terminal.rgs.txt、style_terminal.h、style_terminal.png 以及字体 Mecha.ttf、字符集 charset.txt,并未包含 style_terminal.old.rgs 文件;若需 raygui 3.x 兼容格式,需自行转换或关注后续仓库更新。

除 Terminal 风格外,raygui 还提供了 dark、bluish、candy、cyber、jungle 等 20 款内置风格,统一入口与说明见 styles/README.md,这些风格均需 raylib 6.x 与 raygui 5.x 支持(见 styles/README.md)。

接入方式一:运行时加载二进制 .rgs 文件

最直接的接入方式是在初始化时调用 GuiLoadStyle() 加载 .rgs 文件(对应 src/raygui.h 的声明):

#include "raylib.h"
#define RAYGUI_IMPLEMENTATION
#include "raygui.h"

int main(void)
{
    InitWindow(800, 600, "Terminal Style Demo");

    // 在初始化阶段加载 Terminal 风格(.rgs 默认是二进制文件)
    GuiLoadStyle("resources/styles/terminal/style_terminal.rgs");

    while (!WindowShouldClose())
    {
        BeginDrawing();
        ClearBackground(GetColor(GuiGetStyle(DEFAULT, BACKGROUND_COLOR)));
        // ... 绘制 GuiButton()、GuiTextBox() 等控件
        EndDrawing();
    }

    CloseWindow();
    return 0;
}

GuiLoadStyle() 的实现位于 src/raygui.h,其加载策略是先尝试以文本方式打开:若文件首字符是 # 则按文本 rgs 解析;否则标记 tryBinary,再以二进制方式读取整个文件并转交 GuiLoadStyleFromMemory() 处理(src/raygui.h)。因此同一个 API 可同时兼容文本与二进制两种 rgs 文件。

二进制 rgs 文件格式剖析

GuiLoadStyleFromMemory() 的注释块完整定义了 rgs 二进制结构(src/raygui.h):

偏移    | 大小   | 类型   | 说明
0       | 4      | char   | 签名:"rGS "(0x72 0x47 0x53 0x20)
4       | 2      | short  | 版本号:200 / 400 / 600
6       | 2      | short  | 保留字段
8       | 4      | int    | 属性数量(仅记录与默认风格不同的属性)

之后是每 8 字节一条的属性记录(ControlId + PropertyId + PropertyValue),再往后是可选的字体数据:字体参数(版本 ≥600 时含 32 字节字体文件名、baseSize、glyphCount、字体类型、白色矩形)、字体 atlas 图像(可 DEFLATE 压缩)、字形矩形 recs 与字形信息 glyphs(版本 ≥400 支持压缩)。

以仓库中的 style_terminal.rgs 实测文件头验证:

72 47 53 20   -> "rGS " 签名
58 02         -> 0x0258 = 600(v600 格式)
00 00         -> 保留字段
11 00 00 00   -> 17 个属性

随后紧跟 17 条属性数据,与文本文件中的 17 行 p 记录一一对应;属性之后即为字体数据段(Mecha.ttf 文件名、baseSize=16、glyphCount=175 等)。这正是 style_terminal.h 中 TERMINAL_STYLE_PROPS_COUNT 17 的来源。

两种版本的压缩差异

  • 版本 ≥400:recs 与 glyphs 数据段各带一个"压缩后大小"字段,支持 DEFLATE 压缩;加载时若 compSize != 原始大小 则调用 DecompressData() 解压,并做解压尺寸安全检查(src/raygui.h)。
  • raygui 3.x(版本 200):无压缩支持,recs/glyphs 原样存储——这正是原 README 中 style_terminal.old.rgs "字体数据未压缩(recs, glyphs)"注释的由来。

接入方式二:文本 .rgs 文件加载(外部字体)

若希望样式文件可读、可手工编辑,且能自行控制字体文件,可使用文本格式 style_terminal.rgs.txt。该文件不含字体数据,需要将 Mecha.ttf 与 charset.txt 一同随附。其完整内容如下:

#
# rgs style text file - raygui style file generated using rGuiStyler
#
# Provided info:
#    f <fontGenSize> <fontFileName> <charsetFileName>
#    p <controlId> <propertyId> <propertyValue>  Property description
#
# WARNING: This style uses a custom font, must be provided with style file
#
v 600
f 16 Mecha.ttf charset.txt
p 00 00 0x1c8d00ff    DEFAULT_BORDER_COLOR_NORMAL
p 00 01 0x161313ff    DEFAULT_BASE_COLOR_NORMAL
p 00 02 0x38f620ff    DEFAULT_TEXT_COLOR_NORMAL
p 00 03 0xc3fbc6ff    DEFAULT_BORDER_COLOR_FOCUSED
p 00 04 0x43bf2eff    DEFAULT_BASE_COLOR_FOCUSED
p 00 05 0xdcfadcff    DEFAULT_TEXT_COLOR_FOCUSED
p 00 06 0x1f5b19ff    DEFAULT_BORDER_COLOR_PRESSED
p 00 07 0x43ff28ff    DEFAULT_BASE_COLOR_PRESSED
p 00 08 0x1e6f15ff    DEFAULT_TEXT_COLOR_PRESSED
p 00 09 0x223b22ff    DEFAULT_BORDER_COLOR_DISABLED
p 00 10 0x182c18ff    DEFAULT_BASE_COLOR_DISABLED
p 00 11 0x244125ff    DEFAULT_TEXT_COLOR_DISABLED
p 00 16 0x00000010    TEXT_SIZE
p 00 17 0x00000000    TEXT_SPACING
p 00 18 0xe6fce3ff    LINE_COLOR
p 00 19 0x0c1505ff    BACKGROUND_COLOR
p 00 20 0x00000008    TEXT_LINE_SPACING

语法说明(对应 GuiLoadStyle() 文本解析逻辑,src/raygui.h):

  • v 600:样式版本号,版本 ≥600 时字体行按 f <字号> <字体文件> <字符集文件> 顺序解析(旧版本顺序相反)。
  • f 16 Mecha.ttf charset.txt:字体声明。加载时 LoadFileText() 读取同目录下的 charset.txt,经 LoadCodepoints() 得到码点列表,再 LoadFontEx() 按指定字号(16)加载字体(src/raygui.h)。若字体纹理加载失败,会自动回退到默认字体并将 TEXT_SIZE 重置为 10、TEXT_SPACING 重置为 1(src/raygui.h)。
  • p 00 00 0x1c8d00ff:属性行,格式为 p <controlId> <propertyId> <propertyValue>,00 表示 DEFAULT 控件。加载时通过 GuiSetStyle() 写入全局样式数组。

使用示例:

// 文本 rgs 需要与 Mecha.ttf、charset.txt 放在同一目录
GuiLoadStyle("resources/styles/terminal/style_terminal.rgs.txt");

接入方式三:嵌入 .h 源码文件(自包含,零外部资源)

若希望应用完全自包含、不依赖任何外部文件,推荐直接嵌入 style_terminal.h。该文件由 StyleAsCode exporter v2.0 生成,头部明确标注用法:"On init call: GuiLoadStyleTerminal();"。

在 style_selector.c 示例中即采用了这种方式:

#define RAYGUI_IMPLEMENTATION
#include "../../src/raygui.h"

// raygui embedded styles
#include "../styles/style_terminal.h"          // raygui style: terminal
// ...

// 初始化阶段调用
GuiLoadStyleTerminal();

GuiLoadStyleTerminal() 的完整实现见 style_terminal.h,其内部流程清晰呈现了嵌入样式的自包含原理:

  1. 写入 17 条样式属性:遍历 terminalStyleProps<a href="https://link.gitcode.com/i/a627425100f1176c78554ce9ca943511" target="_blank">] 数组逐条 GuiSetStyle(),默认属性会自动传播到其余控件(与 GuiLoadStyleFromMemory() 中 controlId=0 时的传播行为一致,见 [src/raygui.h)。
  2. 解压字体 atlas:terminalFontData<a href="https://link.gitcode.com/i/f08b9a550a4915ea6769b13eff184d90" target="_blank">] 是 DEFLATE 压缩的 256×256 GRAY+ALPHA 字体图集(压缩后 1731 字节,定义于 [style_terminal.h),通过 DecompressData() 解压后构造 Image。
  3. 组装字体:baseSize = 16、glyphCount = 175;terminalFontRecs<a href="https://link.gitcode.com/i/1ab5baf7f4ca79e1fd1a782317a93654" target="_blank">](175 个 Rectangle)与 terminalFontGlyphs[](175 个 GlyphInfo,含码点/偏移/步进)分别拷贝到 RAYGUI_CALLOC 分配的内存中——注释说明这是"为避免释放字体时出错"的必要拷贝([style_terminal.h)。
  4. 加载纹理并挂载字体:LoadTextureFromImage() 生成纹理后 UnloadImage() 释放解压数据,再 GuiSetFont(font);同时 SetShapesTexture() 将形状绘制的白色矩形指向字体图集,实现 UI 形状与文字的单次绘制优化(style_terminal.h)。
  5. 记录字体名:通过 snprintf() 将 "Mecha.ttf" 写入内部 guiFontName(需 raygui 5.0,style_terminal.h)。
// 嵌入方式:无需任何外部文件
#include "style_terminal.h"
// 初始化阶段调用
GuiLoadStyleTerminal();

嵌入方式下若同时启用 RAYGUI_FONT_ICONS_BAKING,还会调用 GuiFontIconBaking() 将图标烘焙进字体图集并更新白色矩形位置(style_terminal.h)。

接入方式四与五:样式表 PNG 与运行时拖拽

  • 样式表 PNG(rGSf chunk):style_terminal.png 不仅用于预览,其图像数据内嵌了 rGSf chunk,携带完整二进制 rgs 文件数据。可将 PNG 当作载体分发样式,运行时从中提取 rgs 数据后调用 GuiLoadStyleFromMemory()(仅支持二进制,见 src/raygui.h 的声明注释)。
  • 运行时热切换:style_selector.c 还演示了拖拽加载——检测到 .rgs 文件被拖入窗口即调用 GuiLoadStyle(路径)(style_selector.c);切换风格前先调用 GuiLoadStyleDefault() 重置并卸载先前加载的字体纹理(style_selector.c),该 API 的声明位于 src/raygui.h。

配色方案参数全表

综合 style_terminal.h 与文本 rgs,Terminal 风格共修改 17 项默认属性(DEFAULT 控件,controlId=0),颜色均为 0xRRGGBBAA 格式:

属性(propertyId) 值 含义
BORDER_COLOR_NORMAL (0) 0x1c8d00ff 正常态边框:深绿
BASE_COLOR_NORMAL (1) 0x161313ff 正常态底色:近黑
TEXT_COLOR_NORMAL (2) 0x38f620ff 正常态文字:荧光绿
BORDER_COLOR_FOCUSED (3) 0xc3fbc6ff 聚焦态边框:浅绿白
BASE_COLOR_FOCUSED (4) 0x43bf2eff 聚焦态底色:中绿
TEXT_COLOR_FOCUSED (5) 0xdcfadcff 聚焦态文字:近白绿
BORDER_COLOR_PRESSED (6) 0x1f5b19ff 按下态边框:暗绿
BASE_COLOR_PRESSED (7) 0x43ff28ff 按下态底色:亮绿
TEXT_COLOR_PRESSED (8) 0x1e6f15ff 按下态文字:深绿
BORDER_COLOR_DISABLED (9) 0x223b22ff 禁用态边框:暗墨绿
BASE_COLOR_DISABLED (10) 0x182c18ff 禁用态底色:深墨绿
TEXT_COLOR_DISABLED (11) 0x244125ff 禁用态文字:灰绿
TEXT_SIZE (16) 16 全局字号(由字体生成尺寸决定)
TEXT_SPACING (17) 0 字符间距
LINE_COLOR (18) 0xe6fce3ff 分隔线/面板线颜色:浅绿白
BACKGROUND_COLOR (19) 0x0c1505ff 全局背景:极暗墨绿
TEXT_LINE_SPACING (20) 8 文本行间距

其中 TEXT_SIZE 由字体加载决定,因此在 GuiLoadStyleTerminal() 中直接取自 font.baseSize = 16,而文本 rgs 的 f 16 与二进制 rgs 中记录的 0x10(16)完全一致。若加载失败回退默认字体,TEXT_SIZE 会自动改为 10。

关于字体:Mecha

Terminal 风格使用 Mecha 字体,作者 Captain Falcon,为 100% 免费字体(原 README 注明可从 dafont.com 的 mecha-cf 页面下载)。该字体风格硬朗、几何感强,与终端主题的科技气质高度契合。

字体相关细节(可从 style_terminal.h 与 charset.txt 确认):

  • 字符集:charset.txt 定义了 175 个码点,覆盖 ASCII 全量字符及 Latin-1 补充字符(含 ¡ ¢ £ € ¥ Š § š © ª « ¬ ® ¯ ° ± ² ³ Ž µ ¶ · ž ¹ º » Œ œ Ÿ ¿ À … ÿ 等),对应 glyphCount = 175。
  • 图集:256×256 GRAY+ALPHA,DEFLATE 压缩后仅 1731 字节;175 个字形矩形与字形度量信息随样式一并固化在头文件中。
  • 字号与间距:baseSize 16、spacing 0。

注意事项与版本要求

  • 版本依赖:Terminal 风格属 raygui 5.x / raylib 6.x 时代产物(styles/README.md 明确所有内置风格均要求 raylib 6.x 与 raygui 5.x);guiFontName 写入逻辑需 raygui 5.0(style_terminal.h)。
  • rgs 版本兼容:二进制 rgs 支持 200 / 400 / 600 三个版本号(src/raygui.h)。Terminal 的二进制文件为 v600;若面向 raygui 3.x 旧版本,则需使用未压缩的 .old.rgs 格式(本仓库未提供该文件)。
  • 切换样式前重置:GuiLoadStyleDefault() 会卸载先前加载的自定义字体纹理并恢复默认样式,风格热切换时必须先调用它(参考 style_selector.c)。
  • 文本 rgs 的字体路径:文本加载时字体与字符集文件按"rgs 所在目录"解析(GetDirectoryPath(fileName) 拼接,见 src/raygui.h),部署时需保证 Mecha.ttf 与 charset.txt 与文本 rgs 同目录。
  • 嵌入头文件的代价:.h 方式自包含、无外部依赖,但把 1731 字节压缩图集与 175 条字形数据全部编入源码,会增加编译单元体积;对二进制体积敏感的项目可改用外部 .rgs 运行时加载。

综上,Terminal 风格为 raygui 开发者提供了"文件加载"与"代码嵌入"两条完整路径:前者适合资源目录化管理与运行期热切换,后者适合单文件分发与零依赖部署;配合 styles/terminal/README.md 提供的文件清单与 style_selector.c 的可运行示例,可在数分钟内为应用接入这一经典终端主题。

登录后查看全文
raygui