gmux 设置页帮助
gmux 设置页帮助
本文档从 设置窗口 的视角讲清楚 gmux 的核心概念，以及内置快捷键的用法和作用。打开托盘图标 → 「设置」就能看到下面提到的所有页面。
侧边栏从上到下依次是：显示器 / 显示场景 / 布局 / 快捷键 / 系统 / 帮助。这六页正好对应「先告诉 gmux 我有哪些屏」→「把屏组合成命名场景」→「为场景写布局并绑定快捷键」→「调整触发键」的工作流。
一、关键概念
gmux 的所有功能都围绕五个概念展开。它们互相依赖，关系如下：
显示器（Display）── 注册成 ──▶ 显示场景（Profile）
▲
│ 引用
│
绑定（Binding）── 包含若干 ──▶ 预案（Variant）
│
└── 引用 ── 布局类别（category）+ 槽位（slot）
└── 引用 ── 应用（app）
触发顺序：按下绑定的快捷键 → 引擎从该 binding 的多个 variant 里挑一个匹配当前显示器的 → 把 variant 里声明的应用放到对应槽位。
1. 显示器（Display）
对应设置页：显示器。
「显示器」是 gmux 对一块物理屏的命名注册。新装第一次启动时，gmux 会自动探测当前接入的所有屏并注册一份。
每条显示器记录包含：
| 字段 | 含义 |
|---|---|
id |
物理 ID（EDID 序列号 + 型号），同型号多屏靠它区分；__PRIMARY__ 是「当前主屏」的占位符 |
name |
你给它起的名字（如 main、vertical、laptop），后续在显示场景和预案里都引用这个名字 |
orientation |
朝向：landscape（横屏）/ portrait（竖屏） |
为什么注册名而不是直接用物理 ID：换机或换屏后只要把同名再注册一遍，所有引用都不用动。同一块屏旋转后视为不同记录（横版 + 竖版可以分别注册）。
页面操作：
- 重新探测：刷新当前接入的物理屏列表；同时短暂在每块屏上画出对应编号便于辨认。
- 隐藏显示器编号：手动关闭那个编号 OSD。
- 未命名卡片 → 注册：填一个名字然后保存，那块屏就进入「已注册」区。
- 被某个显示场景引用 时，该卡片不能直接编辑或删除，需先去显示场景页解绑。
2. 显示场景（Profile）
对应设置页：显示场景。
「显示场景」= 一组已注册显示器的有序集合，代表一种物理使用环境。例如：
solo—— 只用主屏home—— 主屏 + 右侧竖屏office—— 左屏 + 主屏 + 右侧笔记本
每个绑定的「预案」必须挂在某个场景上。引擎在触发绑定时，按当前实际接入的屏挑出匹配的场景对应的预案。
每条场景记录包含：
| 字段 | 含义 |
|---|---|
name |
场景名（如 home） |
displays |
屏的有序列表，按拖拽顺序保存；UI 上看到的编号即列表下标 |
first_as_default |
把列表第一块屏当作「默认屏」，影响 prefix+w 面板和 split 兜底落屏 |
quick_swap |
可选的两块屏对，被 prefix+mm 快捷键专门用于交换 |
页面操作：
- 新建显示场景：从已注册显示器池子里拖一组进入预览区，按预期摆位调整顺序。
- 拖拽场景卡片排序：决定显示场景在 OSD 列表里的展示顺序。
- 引擎在加载配置时会比对当前物理屏，匹配上的场景显示为「在线」，否则会有锁标记说明被哪个绑定引用、暂时不可编辑。
3. 绑定（Binding）
对应设置页：布局（左栏一个个条目就是绑定）。
「绑定」= 一个快捷键 + 描述 + 一组预案。绑定的 key 可以是按键选择器里的任意单键 —— 数字 0-9、字母 a-z、功能键 F1–F24、命名键（Space、Enter、Tab、方向键、Home/End 等）或 OEM 标点（; / [ ] 等），共 85 个。（数字和字母默认展开；功能键、命名键、标点在选择器的折叠分区里。）按 prefix + <key> 就触发它（默认 prefix 是 Ctrl+M，所以是 Ctrl+M 1 / Ctrl+M a 这种形式）。
每条绑定包含：
| 字段 | 含义 |
|---|---|
id |
触发键，如 1 或 a |
description |
绑定描述（左栏显示的标题，如「开发」「会议」「单屏阅读」） |
variants |
一个或多个预案；引擎按当前屏配置挑一个执行 |
页面操作：
- 新建绑定：填描述 + 选触发键。已被占用的触发键会在选择器里标灰。
- 删除绑定：连同所有预案一并删除；触发键变为可用。
- 重命名：右上角 ✎ 图标改 description，触发键不变。
- 左栏排序：决定绑定在 prefix+w 列表里的展示顺序。
免费版上限是 9 个绑定；超过需要升级或试用。
4. 预案（Variant）
对应设置页：布局（右侧详情区里的「预案卡片」）。
「预案」= 同一个绑定在某个显示场景下的具体布局描述。一个绑定可以有多个预案，分别绑不同的场景，引擎按当前接入屏自动选。
例：绑定「开发」可以挂三套预案 —— 双屏
home用左屏 IDE/右屏文档，三屏office用左屏 IDE / 中屏 Chrome / 右屏 Slack，单屏solo用主屏满屏 IDE。出门带笔记本时，只有solo匹配，按Ctrl+M 1就走 solo 那套。
每条预案包含：
| 字段 | 含义 |
|---|---|
profile |
预案绑定的显示场景名 |
categories |
给场景里每块屏指定的布局类别（横屏 / 竖屏分别有 12 个内置类别 + 通用 full） |
regions |
应用与槽位的对应表：哪个 app 放在哪块屏的哪个槽位 |
布局类别（category）+ 槽位（slot） 是几何模板：
- 类别决定一块屏被如何切分（如
quad_h= 四象限，halves_h= 左右两半，thirds_v= 竖向三段）。 - 槽位是切分后每块小区域的命名（如
tl/tr/bl/br、left/right、top/middle/bottom）。 - 一块屏选一个类别，类别决定了它有哪些可填的槽位。
- 共 25 个内置类别（横屏 12 + 竖屏 12 + 通用
full），无法自定义 —— 保持固定才能让 GUI 编辑器永远「认得」配置。
页面操作：
- 关联显示场景：在绑定详情区点 +，新建一条预案；选场景 → 给每屏挑类别 → 把应用拖进槽位。
- 编辑：预案卡片右上角「编辑」图标进入抽屉。
- 当前生效的预案会在卡片上打「当前生效」标识；不匹配当前物理屏的预案会标「不匹配」。
- 应用可以从「已注册」区选，也可以从系统 Start Menu / UWP 列表里挑，第一次选会自动写入应用注册表。
免费版限制：每个预案只能涉及一块屏；多屏预案需要 Premium。
5. 一句话串起来
一台机器接哪些屏 → 注册成「显示器」。 几块屏组成一种使用环境 → 命名为「显示场景」。 想用什么快捷键切一种工作姿势 → 建一个「绑定」。 同一个绑定在不同场景下要做的事不同 → 写多份「预案」。 每份预案描述每块屏切几块、谁在哪块 → 类别 + 槽位 + 应用。
二、系统预设快捷键
对应设置页：快捷键（左栏「prefix 键」「动作快捷键」「高级」三块）。
gmux 是一个 prefix + chord 系统：先按 prefix 进入「等待第二键」状态，再按一个键触发动作。Prefix 默认 Ctrl+M，所有内置动作都需要先按 prefix。
「设置 → 快捷键」页面允许修改 prefix、修改每个动作的第二键、调整超时；下面列出的都是首次启动的默认值。
每一项都有独立的详细文档，描述所有可能的用法分支、取消条件和拒绝条件。下表里点动作名即可跳转。
2.1 Prefix（前缀键）
| 设置项 | 默认值 | 作用 |
|---|---|---|
prefix |
Ctrl+M |
进入「等待 chord」状态的总开关 |
| 启用 Win 键作为修饰键 | 关 | 勾上才允许把 Win 当 prefix 的修饰键 |
| PREFIX 超时 | 2000 ms | 按下 prefix 后等待第二键的最长时间 |
修改方式：「快捷键 → prefix 键」点编辑按钮，按下新组合保存。Prefix 至少要带一个修饰键（Ctrl / Alt / Shift / Win），不允许单独的字母数字。
提示：如果托盘图标变红，说明 prefix 被别的应用抢占了；换一个组合或先关掉抢占者，再去托盘点「重试 prefix」。
完整说明：hotkeys/prefix-zh.md
2.2 触发绑定
按下 prefix 后输入绑定 key 就触发对应布局：
| 按键序列 | 作用 |
|---|---|
prefix <绑定键> |
触发 bindings.<key>（0-9、a-z、F1–F24、命名键或 OEM 标点）—— 引擎挑一个匹配的预案、把窗口摆到位 |
绑定列表的当前 key 在「布局」页的左栏（如「⌃M·1」就是 Ctrl+M 后按 1）。绑定触发的细节（包括 prefix 模式的取消语义）见 hotkeys/prefix-zh.md。
2.3 布局导航类动作
页面分类：「快捷键 → 动作快捷键 → 布局导航」。
| 动作名 | 默认键 | 完整序列 | 作用 |
|---|---|---|---|
next_layout |
n |
Ctrl+M n |
切到「下一个」布局；连续按可在所有 binding 之间循环 |
prev_layout |
p |
Ctrl+M p |
切到「上一个」布局，反向循环 |
last_layout |
l |
Ctrl+M l |
跳到上次使用过的布局（适合两套布局来回切） |
restore |
r |
Ctrl+M r |
重新把当前布局应用一遍：清掉临时全屏、恢复被手动拖动的窗口位置 |
show_desktop |
space |
Ctrl+M Space |
显示桌面 / 还原（系统级 Win+D 的等效，但走 prefix） |
list_layouts |
w |
Ctrl+M w |
弹出 OSD 列出所有布局；用 hjkl 选、Enter 确认、Esc 取消 |
2.4 区域操作类动作
页面分类：「快捷键 → 动作快捷键 → 区域操作」。
「区域（region）」= 当前预案的某一块屏 × 某一个槽位。例如四象限的左上、左右两半的左半。这些动作都需要先选中一个区域，或在动作中指定区域。
| 动作名 | 默认键 | 完整序列 | 作用 |
|---|---|---|---|
show_regions |
q |
Ctrl+M q <digit> 或 Ctrl+M q q <digits> Enter |
屏幕上画出所有 region 编号；按数字选中（≥10 时进多位输入模式） |
cycle_region |
f |
Ctrl+M f |
在已选 region 里，把当前 app 的下一个窗口轮换上来 |
fullscreen |
z |
Ctrl+M z |
已选 region 临时全屏；再按一次还原（同屏单全屏） |
focus_region |
g |
Ctrl+M g |
把焦点 + 鼠标跳到已选 region 的窗口（不动窗口位置） |
split_region |
c |
Ctrl+M c 然后弹应用选择器 |
在已选 region 内追加一个应用（区域被切分） |
close_window |
x |
Ctrl+M x |
关闭已选 region 的当前窗口（异步 WM_CLOSE） |
collapse_region |
d |
Ctrl+M d |
回收已选 region 并最小化其窗口——不关闭，可逆 |
swap_displays |
m |
Ctrl+M m m 或 Ctrl+M m <digit><digit> |
交换两块屏的整套布局 |
swap_displays 是 chord 中分支最多的一条，在 hotkeys/swap-displays-zh.md 里有完整的三种用法（mm / m+数字+数字 / 取消）说明。
2.5 帮助
| 动作名 | 默认键 | 完整序列 | 作用 |
|---|---|---|---|
open_help |
? |
Ctrl+M ? |
打开「帮助 / 速查表」窗口；引擎里 ? 等价于 / 键，无需按 Shift |
设置窗口在显示时也支持 F1 直接打开「帮助」页。
2.6 高级时序
「快捷键 → 高级」里能调整四个 ms 级超时和并发上限：
| 设置项 | 默认值 | 作用 |
|---|---|---|
循环超时（cycle_timeout_ms） |
3000 ms | next/prev 连按时被视为同一次循环会话的最长间隔 |
LAYOUT LIST OSD 上限（layout_list_timeout_ms） |
30000 ms | list_layouts OSD 自动关闭时间 |
命令键后输入超时（input_timeout_ms） |
3000 ms | prefix+q 选区 / prefix+m 交换显示器时，命令键之后每个按键的超时；每按一键重置 |
REGION OSD 清理间隔（region_cleanup_interval_ms） |
1000 ms | region OSD 内部清理 tick |
启动并发上限（max_parallel_launches） |
0（自动） | 一次绑定触发时同时冷启动多少个应用；0 = 按 CPU 自动计算，1–32 = 固定值 |
2.7 静默操作提示
「快捷键 → 静默操作提示」打开后，按下热键但前置条件不满足时（如没有可用 layout、region 太小、没选中区域），会在默认屏中央弹一行短提示，避免「以为没反应其实是被静默丢弃」。同一条提示 3 秒内只弹一次。
2.8 一键恢复默认
「快捷键」页右上的「恢复默认」按钮会把 prefix、所有超时、14 个动作 chord 全部重置回首次启动的默认值。如果默认值会和你已有的某条绑定撞键，恢复会被拒绝并列出冲突，让你先手动改键。
三、其它设置页简述
| 侧边栏入口 | 主要作用 |
|---|---|
| 应用匹配（系统页底部「高级」展开） | 查看每个已注册应用的启动方式与窗口匹配信号；窗口形态变后可重新匹配 |
| 系统 → 语言 | 切换界面语言（跟随系统 / 中文 / English / 日本語） |
| 系统 → 日志 | 设置日志级别、目录、轮转策略，导出诊断包 |
| 帮助 | 速查当前 prefix、所有绑定的触发键、所有动作 chord —— 改完快捷键随时回来确认 |
四、配置文件位置
所有 GUI 改动最终落到一份 TOML：
%APPDATA%\gmux\config.toml
直接编辑这份文件并触发 托盘 → 重新加载配置 也能生效；GUI 是「另一种入口」，不是必经路径。配置可以丢进 git / Dropbox 同步，但 display_profiles 里的 EDID 序列号是特定机器的，跨机器需要重新探测显示器或预先给两台机器对应的屏取一致的 name。