Ghostty C API 实战用 ghostty-vt 的 Focus 编码接口把焦点事件编码为终端转义序列【免费下载链接】ghostty Ghostty is a fast, feature-rich, and cross-platform terminal emulator that uses platform-native UI and GPU acceleration.项目地址: https://gitcode.com/GitHub_Trending/gh/ghosttyGhostty 除了作为完整终端仿真器之外还对外发布了名为ghostty-vt的标准 C 库libghostty其中包含一组轻量的“编码”辅助接口。example/c-vt-encode-focus示例演示了其中最简单的一类用法调用ghostty_focus_encode()把“窗口获得焦点 / 失去焦点”事件编码为终端转义序列CSI I / CSI O。读完本文你将掌握如何编写并构建一个链接ghostty-vt的 C 程序理解该接口的函数签名、返回约定与缓冲区语义并能从源码层面确认它实际输出的是哪几个字节。示例的定位与运行方式该示例位于仓库的 example/c-vt-encode-focus 目录其 README 说明这是一个展示如何使用ghostty-vtfocus 编码 API 把 focus gained/lost 事件编码为转义序列的简单示例。示例本身是 C 程序但通过build.zig和 Zig 构建系统来编译——这样做可以直接复用 Ghostty 仓库的构建逻辑并依赖源码树本身而 Ghostty 实际发布的是标准 C 库任何 C 工具链都可以链接使用。按照 example/README.md 的统一约定所有示例包括以c-开头的 C API 示例都可以进入目录后执行以下命令构建并运行cd example/c-vt-encode-focus zig build run其中zig build run是 build.zig 中注册的run步骤它依赖 install 步骤先编译产物再执行。完整的 C 示例代码示例的全部 C 源码只有 src/main.c 一个文件#include stdio.h #include ghostty/vt.h //! [focus-encode] int main() { char buf[8]; size_t written 0; GhosttyResult result ghostty_focus_encode( GHOSTTY_FOCUS_GAINED, buf, sizeof(buf), written); if (result GHOSTTY_SUCCESS) { printf(Encoded %zu bytes: , written); fwrite(buf, 1, written, stdout); printf(\n); } return 0; } //! [focus-encode]代码要点调用ghostty_focus_encode()时传入事件GHOSTTY_FOCUS_GAINED获得焦点一个 8 字节的输出缓冲区buf缓冲区长度sizeof(buf)以及输出参数written用于接收实际写入的字节数只有当返回值等于GHOSTTY_SUCCESS时才把written字节写入 stdout源码中的//! [focus-encode]标记不是注释的普通内容而是 Doxygen 的 snippet 边界标记见下文“与文档系统联动”一节。示例选用 8 字节缓冲区并非偶然设计而是出于健壮性考虑底层实现保证一次编码最多只写 3 个字节见下节8 字节足以容纳同时演示了“调用方提供缓冲区”这一 API 约定。接口定义include/ghostty/vt/focus.h该接口的权威定义在头文件 include/ghostty/vt/focus.h 中头部注释说明这是 “focus encoding” 模块——把 focus in/out 事件编码为终端转义序列CSI I / CSI O服务于焦点报告模式focus reporting mode即 mode 1004。焦点事件由一个枚举表示/** * Focus event types for focus reporting mode (mode 1004). */ typedef enum GHOSTTY_ENUM_TYPED { /** Terminal window gained focus */ GHOSTTY_FOCUS_GAINED 0, /** Terminal window lost focus */ GHOSTTY_FOCUS_LOST 1, GHOSTTY_FOCUS_MAX_VALUE GHOSTTY_ENUM_MAX_VALUE, } GhosttyFocusEvent;编码函数原型为GHOSTTY_API GhosttyResult ghostty_focus_encode( GhosttyFocusEvent event, char* buf, size_t buf_len, size_t* out_written);参数语义来自头文件注释参数说明event要编码的焦点事件GHOSTTY_FOCUS_GAINED或GHOSTTY_FOCUS_LOSTbuf输出缓冲区写入编码后的转义序列可以为 NULLbuf_len输出缓冲区的字节容量out_written成功时写入实际写入的字节数缓冲区不足时写入所需缓冲区大小返回值约定是该 API 值得注意的设计成功返回GHOSTTY_SUCCESS若缓冲区太小则返回GHOSTTY_OUT_OF_SPACE并把所需大小写回out_written调用方据此用足够大的缓冲区重试。也就是说buf允许为 NULL 时可以用一次调用探测所需长度这是嵌入式场景下典型的“先量后写”契约。底层实现实际输出的是哪几个字节ghostty_focus_encode是 C 导出符号真正的实现在 Zig 侧。src/lib_vt.zig 中有显式导出export(c.focus_encode, .{ .name ghostty_focus_encode });该符号指向 src/terminal/focus.zig 中的encode函数/// Maximum number of bytes that encode will write. Any users of this /// should be resilient to this changing, so this is always a specific /// value (e.g. we dont add unnecessary padding). pub const max_encode_size 3; /// Encode a focus in/out report (CSI I / CSI O). pub fn encode( writer: *std.Io.Writer, event: Event, ) std.Io.Writer.Error!void { try writer.writeAll(switch (event) { .gained \x1B[I, .lost \x1B[O, }); }由此可以确认几个实现事实获得焦点输出 3 个字节ESC [ I即\x1B[ICSI I失去焦点输出ESC [ O即\x1B[OCSI O编码结果的上限是常量max_encode_size 3因此示例中 8 字节的栈缓冲区必然足够GHOSTTY_OUT_OF_SPACE分支在该场景下不会触发同一文件内还附带了两个单元测试test encode focus gained/test encode focus lost用固定缓冲区 writer 断言两种事件分别编码为\x1B[I和\x1B[O]是验证该接口行为的最直接依据。从源码结构看focus.zig是终端内部实现而 C 库通过src/terminal/c/focus.zig中的encode包装经由 src/terminal/c/main.zig 的pub const focus_encode focus.encode;对外暴露形成“C 头文件声明 → 导出符号 → Zig 编码函数”的调用链。构建系统build.zig 与 build.zig.zon这个示例也完整展示了第三方项目如何依赖ghostty-vt。build.zig 的核心逻辑const exe_mod b.createModule(.{ .target target, .optimize optimize }); exe_mod.addCSourceFiles(.{ .root b.path(src), .files .{main.c} }); // 使用 lazy dependency只有真正需要时才解析 ghostty 依赖 if (b.lazyDependency(ghostty, .{ /* .simd false 可做纯静态构建无 libc但有明显性能损耗 */ })) |dep| { exe_mod.linkLibrary(dep.artifact(ghostty-vt)); } const exe b.addExecutable(.{ .name c_vt_encode_focus, .root_module exe_mod }); b.installArtifact(exe);关键约定可执行目标名使用下划线c_vt_encode_focus对应目录名中的连字符这是 example 目录的统一规范通过lazyDependency(ghostty, ...)链接ghostty-vtartifact注释同时说明设置.simd false会强制得到不依赖 libc 的纯静态构建但性能代价显著——如果宿主应用本就依赖 libc应保持 simd 启用依赖声明在 build.zig.zon 中。仓库内的示例使用路径依赖.ghostty .{ .path ../../ }以便始终对照随示例捆绑的源码树进行测试zon 文件里保留了注释掉的 URL 依赖写法示例说明真实外部项目通常用带 hash 的 URL 归档依赖指向某个固定提交minimum_zig_version为0.15.1。与文档系统联动snippet 标记的由来回到src/main.c里那两行//! [focus-encode]。example/AGENTS.md 解释了这一约定示例源码使用 Doxygen snippet 标记让 include/ghostty/vt/focus.h 等头文件通过snippet c-vt-encode-focus/src/main.c focus-encode引用同一份代码而不是在头文件里重复内联代码块。这正是头文件中“Basic Usage / Example”一节直接指向本示例的原因——修改示例代码时需要保持 snippet 标记与头文件引用同步。另外example 目录约定所有新示例会被 CI 通过example/*/build.zig.zon通配自动发现因此该示例同时充当了仓库自身的构建与文档集成样例。小结c-vt-encode-focus用不到 20 行 C 代码展示了嵌入ghostty-vt的最小路径包含ghostty/vt.h→ 调用ghostty_focus_encode(GHOSTTY_FOCUS_GAINED, buf, len, written)→ 检查GHOSTTY_SUCCESS并消费out_written。底层实现确认其输出固定为 3 字节的 CSI Isrc/terminal/focus.zig中的max_encode_size且配套单元测试覆盖了 gained/lost 两种事件。若你的终端嵌入场景需要向应用转发窗口焦点变化配合 mode 1004 焦点报告可以直接以 example/c-vt-encode-focus 为模板替换依赖声明为指向发布归档的 URL 依赖即可脱离 Ghostty 源码树独立构建。【免费下载链接】ghostty Ghostty is a fast, feature-rich, and cross-platform terminal emulator that uses platform-native UI and GPU acceleration.项目地址: https://gitcode.com/GitHub_Trending/gh/ghostty创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Ghostty C API 实战：用 ghostty-vt 的 Focus 编码接口把焦点事件编码为终端转义序列
Ghostty C API 实战用 ghostty-vt 的 Focus 编码接口把焦点事件编码为终端转义序列【免费下载链接】ghostty Ghostty is a fast, feature-rich, and cross-platform terminal emulator that uses platform-native UI and GPU acceleration.项目地址: https://gitcode.com/GitHub_Trending/gh/ghosttyGhostty 除了作为完整终端仿真器之外还对外发布了名为ghostty-vt的标准 C 库libghostty其中包含一组轻量的“编码”辅助接口。example/c-vt-encode-focus示例演示了其中最简单的一类用法调用ghostty_focus_encode()把“窗口获得焦点 / 失去焦点”事件编码为终端转义序列CSI I / CSI O。读完本文你将掌握如何编写并构建一个链接ghostty-vt的 C 程序理解该接口的函数签名、返回约定与缓冲区语义并能从源码层面确认它实际输出的是哪几个字节。示例的定位与运行方式该示例位于仓库的 example/c-vt-encode-focus 目录其 README 说明这是一个展示如何使用ghostty-vtfocus 编码 API 把 focus gained/lost 事件编码为转义序列的简单示例。示例本身是 C 程序但通过build.zig和 Zig 构建系统来编译——这样做可以直接复用 Ghostty 仓库的构建逻辑并依赖源码树本身而 Ghostty 实际发布的是标准 C 库任何 C 工具链都可以链接使用。按照 example/README.md 的统一约定所有示例包括以c-开头的 C API 示例都可以进入目录后执行以下命令构建并运行cd example/c-vt-encode-focus zig build run其中zig build run是 build.zig 中注册的run步骤它依赖 install 步骤先编译产物再执行。完整的 C 示例代码示例的全部 C 源码只有 src/main.c 一个文件#include stdio.h #include ghostty/vt.h //! [focus-encode] int main() { char buf[8]; size_t written 0; GhosttyResult result ghostty_focus_encode( GHOSTTY_FOCUS_GAINED, buf, sizeof(buf), written); if (result GHOSTTY_SUCCESS) { printf(Encoded %zu bytes: , written); fwrite(buf, 1, written, stdout); printf(\n); } return 0; } //! [focus-encode]代码要点调用ghostty_focus_encode()时传入事件GHOSTTY_FOCUS_GAINED获得焦点一个 8 字节的输出缓冲区buf缓冲区长度sizeof(buf)以及输出参数written用于接收实际写入的字节数只有当返回值等于GHOSTTY_SUCCESS时才把written字节写入 stdout源码中的//! [focus-encode]标记不是注释的普通内容而是 Doxygen 的 snippet 边界标记见下文“与文档系统联动”一节。示例选用 8 字节缓冲区并非偶然设计而是出于健壮性考虑底层实现保证一次编码最多只写 3 个字节见下节8 字节足以容纳同时演示了“调用方提供缓冲区”这一 API 约定。接口定义include/ghostty/vt/focus.h该接口的权威定义在头文件 include/ghostty/vt/focus.h 中头部注释说明这是 “focus encoding” 模块——把 focus in/out 事件编码为终端转义序列CSI I / CSI O服务于焦点报告模式focus reporting mode即 mode 1004。焦点事件由一个枚举表示/** * Focus event types for focus reporting mode (mode 1004). */ typedef enum GHOSTTY_ENUM_TYPED { /** Terminal window gained focus */ GHOSTTY_FOCUS_GAINED 0, /** Terminal window lost focus */ GHOSTTY_FOCUS_LOST 1, GHOSTTY_FOCUS_MAX_VALUE GHOSTTY_ENUM_MAX_VALUE, } GhosttyFocusEvent;编码函数原型为GHOSTTY_API GhosttyResult ghostty_focus_encode( GhosttyFocusEvent event, char* buf, size_t buf_len, size_t* out_written);参数语义来自头文件注释参数说明event要编码的焦点事件GHOSTTY_FOCUS_GAINED或GHOSTTY_FOCUS_LOSTbuf输出缓冲区写入编码后的转义序列可以为 NULLbuf_len输出缓冲区的字节容量out_written成功时写入实际写入的字节数缓冲区不足时写入所需缓冲区大小返回值约定是该 API 值得注意的设计成功返回GHOSTTY_SUCCESS若缓冲区太小则返回GHOSTTY_OUT_OF_SPACE并把所需大小写回out_written调用方据此用足够大的缓冲区重试。也就是说buf允许为 NULL 时可以用一次调用探测所需长度这是嵌入式场景下典型的“先量后写”契约。底层实现实际输出的是哪几个字节ghostty_focus_encode是 C 导出符号真正的实现在 Zig 侧。src/lib_vt.zig 中有显式导出export(c.focus_encode, .{ .name ghostty_focus_encode });该符号指向 src/terminal/focus.zig 中的encode函数/// Maximum number of bytes that encode will write. Any users of this /// should be resilient to this changing, so this is always a specific /// value (e.g. we dont add unnecessary padding). pub const max_encode_size 3; /// Encode a focus in/out report (CSI I / CSI O). pub fn encode( writer: *std.Io.Writer, event: Event, ) std.Io.Writer.Error!void { try writer.writeAll(switch (event) { .gained \x1B[I, .lost \x1B[O, }); }由此可以确认几个实现事实获得焦点输出 3 个字节ESC [ I即\x1B[ICSI I失去焦点输出ESC [ O即\x1B[OCSI O编码结果的上限是常量max_encode_size 3因此示例中 8 字节的栈缓冲区必然足够GHOSTTY_OUT_OF_SPACE分支在该场景下不会触发同一文件内还附带了两个单元测试test encode focus gained/test encode focus lost用固定缓冲区 writer 断言两种事件分别编码为\x1B[I和\x1B[O]是验证该接口行为的最直接依据。从源码结构看focus.zig是终端内部实现而 C 库通过src/terminal/c/focus.zig中的encode包装经由 src/terminal/c/main.zig 的pub const focus_encode focus.encode;对外暴露形成“C 头文件声明 → 导出符号 → Zig 编码函数”的调用链。构建系统build.zig 与 build.zig.zon这个示例也完整展示了第三方项目如何依赖ghostty-vt。build.zig 的核心逻辑const exe_mod b.createModule(.{ .target target, .optimize optimize }); exe_mod.addCSourceFiles(.{ .root b.path(src), .files .{main.c} }); // 使用 lazy dependency只有真正需要时才解析 ghostty 依赖 if (b.lazyDependency(ghostty, .{ /* .simd false 可做纯静态构建无 libc但有明显性能损耗 */ })) |dep| { exe_mod.linkLibrary(dep.artifact(ghostty-vt)); } const exe b.addExecutable(.{ .name c_vt_encode_focus, .root_module exe_mod }); b.installArtifact(exe);关键约定可执行目标名使用下划线c_vt_encode_focus对应目录名中的连字符这是 example 目录的统一规范通过lazyDependency(ghostty, ...)链接ghostty-vtartifact注释同时说明设置.simd false会强制得到不依赖 libc 的纯静态构建但性能代价显著——如果宿主应用本就依赖 libc应保持 simd 启用依赖声明在 build.zig.zon 中。仓库内的示例使用路径依赖.ghostty .{ .path ../../ }以便始终对照随示例捆绑的源码树进行测试zon 文件里保留了注释掉的 URL 依赖写法示例说明真实外部项目通常用带 hash 的 URL 归档依赖指向某个固定提交minimum_zig_version为0.15.1。与文档系统联动snippet 标记的由来回到src/main.c里那两行//! [focus-encode]。example/AGENTS.md 解释了这一约定示例源码使用 Doxygen snippet 标记让 include/ghostty/vt/focus.h 等头文件通过snippet c-vt-encode-focus/src/main.c focus-encode引用同一份代码而不是在头文件里重复内联代码块。这正是头文件中“Basic Usage / Example”一节直接指向本示例的原因——修改示例代码时需要保持 snippet 标记与头文件引用同步。另外example 目录约定所有新示例会被 CI 通过example/*/build.zig.zon通配自动发现因此该示例同时充当了仓库自身的构建与文档集成样例。小结c-vt-encode-focus用不到 20 行 C 代码展示了嵌入ghostty-vt的最小路径包含ghostty/vt.h→ 调用ghostty_focus_encode(GHOSTTY_FOCUS_GAINED, buf, len, written)→ 检查GHOSTTY_SUCCESS并消费out_written。底层实现确认其输出固定为 3 字节的 CSI Isrc/terminal/focus.zig中的max_encode_size且配套单元测试覆盖了 gained/lost 两种事件。若你的终端嵌入场景需要向应用转发窗口焦点变化配合 mode 1004 焦点报告可以直接以 example/c-vt-encode-focus 为模板替换依赖声明为指向发布归档的 URL 依赖即可脱离 Ghostty 源码树独立构建。【免费下载链接】ghostty Ghostty is a fast, feature-rich, and cross-platform terminal emulator that uses platform-native UI and GPU acceleration.项目地址: https://gitcode.com/GitHub_Trending/gh/ghostty创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考