hyprgrass演进史:从event hooks到emulate_touchpad触摸屏手势的完整指南
hyprgrass演进史:从event hooks到emulate_touchpad触摸屏手势的完整指南
hyprgrass 是一款面向 Hyprland 窗口管理器的触摸屏手势插件,让你的触屏支持多指滑动、边缘滑动、长按与捏合,还能通过 emulate_touchpad 动作把触屏"伪装"成触控板。本文将带你回顾它从 event hooks 机制到 emulate_touchpad 的演进过程,并展望未来的路线图 🌱
为什么触屏需要一个手势插件?
Hyprland 的触控板原生就支持三指切换工作区、四指缩放等手势,但触摸屏一直是"空白区":手指划过去,只会点到窗口。
hyprgrass 的目标很简单——把 Wayland 生态中成熟的 wf-touch 触摸手势识别库(致谢见 README.md)搬进 Hyprland,让"三指下滑关窗口""从屏幕边缘滑出切换工作区"这类操作在触屏上一样丝滑。
核心实现由两部分组成:
- 手势识别层:src/gestures/Gestures.hpp,负责把原始触摸点流解析成 swipe / edge / longpress / pinch / tap 等手势模式
- 事件管理层:src/GestureManager.hpp,负责把手势事件分发给你配置的绑定
阶段一:event hooks 时代
早期版本中,hyprgrass 对外暴露的是 event hooks(事件钩子):插件侦测到手势后发出事件,用户再借助外部订阅机制去触发自己的命令。
这种"先侦测、后外发"的模式直观灵活,但有一个先天短板——它只能拿到手势"完成"那一刻的结果,拿不到手势进行中的实时状态。也就是说:
- 无法做"手指走到哪、音量条跟到哪"这类实时跟手效果
- 事件从插件外发出去再回来执行,链路长、延迟高
- 外部订阅方式与 Hyprland 自身日益完善的 Lua 配置体系脱节
项目内保留的 docs/event_hooks.md 如今只剩一句话:
No longer works.
hyprgrass-gesturewith theemulate_touchpadaction is the intended replacement.
这是理解 hyprgrass 演进方向最权威的一句话:event hooks 已正式退役。
阶段二:动作系统,手势"内置化"
淘汰事件外发后,hyprgrass 转向手势动作系统:你声明"什么手势 + 什么动作",动作直接在 Hyprland 进程内执行,响应更快、状态更完整。
这一时期的配置形态(Hyprlang 风格)大致是:
# 三指下滑 → 关闭当前窗口
hyprgrass-gesture = swipe, 3, down, close
# 三指横向滑动 → 切换工作区
hyprgrass-gesture = longpress, 3, horizontal, workspace
除内置动作(workspace、close、float、fullscreen、special、move、resize)外,还支持用 hyprgrass-bind 把手势绑到任意命令。想要实时跟手效果时,官方提供了两个"活动手势"Lua 模块,可单独拷出使用(用法见 docs/configuration.md 的 Live Gesture Extras 一节):
- extras/wpctl.lua:手势滑动物理音量
- extras/brightnessctl.lua:手势调节屏幕亮度
阶段三:emulate_touchpad,让触屏"变触控板" 🎯
真正让 hyprgrass 脱胎换骨的是 emulate_touchpad 动作。
它的思路很巧妙:既然触屏缺少触控板手势,那就由插件向 Hyprland 输入系统注入标准的触控板滑动/捏合事件。你的屏幕上依然是手指,但应用程序和 Hyprland 看到的是一个"拥有四指触控板"的设备——窗口缩放、滚动、缩放动画等原生触控板行为立刻全部可用。
核心实现在 src/EmulateTouchpadGesture.hpp:它继承 Hyprland 的 ITrackpadGesture 接口,在 begin / update / end 三个回调中分别调用 g_pInputManager->onSwipeBegin、onSwipeUpdate 等接口,把触摸手势逐帧"翻译"成触控板手势。注册逻辑位于 src/main.cpp 的 emulate_touchpad 分支。
用法示例:
hl.plugin.hyprgrass.gesture {
pattern = {kind = "edge", origin = "up", direction = "down"},
action = "emulate_touchpad",
emulate_fingers = 4,
emulate_direction = "down",
}
正是这个动作让 event hooks 彻底失去了存在意义:过去要靠"外发事件 + 外部脚本"拼出来的行为,现在一行配置即可原生实现。
Lua 迁移:一次痛快的推倒重来
随着 Hyprland 全面转向 Lua 配置,hyprgrass 也完成了大迁移(当前版本 v0.8.2,见 VERSION),主要破坏性变化记录在 docs/lua_migration.md:
- 插件命名空间从
touch_gestures改为hyprgrass - 旧配置项退役:
workspace_swipe_fingers、workspace_swipe_edge被统一的hl.plugin.hyprgrass.gesture取代(src/main.cpp 中加载配置时还会弹出弃用通知提醒你) - 独立小插件合并:hyprgrass-brightnessctl、hyprgrass-pulse 两个附加载体被移除,改为上面提到的 extras/ 下的 Lua 模块
- 两套绑定接口定型:
hl.plugin.hyprgrass.bind:绑定 dispatcher(如hl.dsp.exec_cmd),支持tap、pinch等模式hl.plugin.hyprgrass.gesture:绑定触控板风格动作(含emulate_touchpad)
迁移后的完整配置项与动作列表,参考 docs/configuration.md。
当前功能与未来路线图
README.md 的功能清单中,四项核心目标已全部勾选完成:
- ✅ Workspace Swipe(滑动切换工作区)
- ✅ Custom commands(自定义命令绑定)
- ✅ Swipe From Edge(边缘滑动)
- ✅ Multi-finger swipe(多指滑动)
面向未来,从代码与工程结构中可以读出几层明确的方向:
- 手势精度打磨:源码中仍留有 TODO/FIXME,例如捏合旋转的角度增量计算(src/GestureManager.cpp)和可调整的手势阈值参数(src/gestures/Gestures.cpp),说明 pinch/rotate 类手势还在迭代
- 与 Hyprland 主分支的紧密跟随:hyprpm.toml 中维护着一长串 Hyprland commit 与 hyprgrass commit 的对照表(commit pins),配合 scripts/ci/pin-latest-hyprland 自动钉版本——插件 API 与 Hyprland 内部实现强耦合,"版本同步"本身就是长期主线
- 可测试性:src/gestures/ 被刻意保持"零 Hyprland 依赖"以便单元测试(见 CONTRIBUTING.md 与 src/gestures/test/README.md),手势识别核心有独立的 MockGestureManager 测试设施
- 可复现构建:flake.nix 提供 Nix Flake 构建入口,scripts/hotreload 支持开发热重载
⚠️ 官方提示:项目仍处 alpha 阶段,早期版本曾有个别 bug 会在卸载插件前让触摸设备不可用,初次使用建议手边备好键盘(README.md 警告区)。
快速上手:三步装好 hyprgrass
- 安装依赖:Hyprland、
glm,构建需要meson与ninja - hyprpm 一键安装:
hyprpm add https://github.com/horriblename/hyprgrass
hyprpm enable hyprgrass
- 调优手感(官方推荐,完整说明见 docs/configuration.md):
hl.config({
plugin = {
hyprgrass = {
sensitivity = 4.0, -- 触屏灵敏度,官方建议调高
long_press_delay = 400, -- 长按判定时间(ms)
},
},
gestures = {
workspace_swipe_touch = true, -- 启用触屏三指切工作区
workspace_swipe_cancel_ratio = 0.15,
},
})
结语
从 event hooks 到 emulate_touchpad,hyprgrass 的演进路径其实就是一次架构思想的转变:从"把手势当信号外发"到"把手势当事件内化"。事件钩子完成了历史使命后体面退场,动作系统 + Lua 配置 + 触控板模拟的组合,让触摸屏在 Hyprland 上第一次拥有了媲美触控板的手感。随着 Hyprland Lua API 的成熟,这个仍在快速迭代中的插件,值得每一位触屏用户持续期待 👀