TiXL 快照控制视图:Parameter 窗口中的逐参数快照控制面设计与实现
TiXL 快照控制视图:Parameter 窗口中的逐参数快照控制面设计与实现
导读
本文基于 TiXL(t3)开源仓库中的实现计划 Plan_SnapshotControlView.md,完整剖析编辑器新增的 Snapshot control view(快照控制视图):当 Parameter 窗口中没有任何子算子被选中、合成(composition)本身处于激活态时,该视图会呈现一张面向"受快照影响的参数"的精细控制面。它补充了 Variations 窗口的缩略图式视觉/混合交互,提供精确到单个参数的写入、回退、删除与按参数启停能力。读完本文,你将理解该功能的定位、已锁定的架构决策、三阶段演进路线(逐算子 → 逐参数 → 按 Section 分组)、控制器索引网格(Controller-index grid)的实现细节,以及全部相关的源码位置。
功能定位:与 Variations 窗口互补的精确控制面
快照控制视图是 Parameter 窗口的一种新状态:当 没有子算子被选中(即合成本身处于激活态) 时出现,为"被快照影响的参数"提供详细控制面。它与 Variations 窗口 的分工是:
- Variations 窗口负责**视觉 / 混合(blending)**界面(缩略图、激活、渐变切换);
- 快照控制视图负责精确到单个参数的读写与回退。
两个 UI 共享同一个 SymbolVariationPool 数据源,因此任何一方的写入/删除都必须立即反映到另一方(激活状态、缩略图保持一致,见 VariationHandling.cs 中的 UpdateActiveStateForVariation 相关路径)。
计划中明确了两份关联文档:分组结构(Section 树)由 Plan_Sections.md 提供,仅在 Phase C 被消费,Phase A、B 不依赖它;选择器栏的快照下拉框由 Plan_VariationPicker.md 替换为可复用的可搜索选择器(含缩略图、激活推子、嵌入式画布模式)。
目标形态:视图包含哪些内容
当合成在 Parameter 窗口中处于激活态时,视图自上而下由三部分组成:
- 快照选择器栏(snapshot selector bar):数字索引指示器、快照下拉框、上一个/下一个箭头按钮,以及三个动作按钮——write(把当前值更新进快照,当值与快照一致时禁用)、revert(重新应用快照)、remove(删除)。
- 受控算子及其受控参数列表:与常规参数视图完全一致的编辑体验(同样的
DrawParameters行机制,编辑、右键菜单、动画指示器行为一致)。点击算子名称会选中它并在图中将其居中。 - Inputs 组:合成输入(可通过
Guid.Empty子 id 捕获进快照)以独立的 "Inputs" 组出现。
后续演进方向:
- Phase B(已完成):快照启用粒度从"逐算子"下沉为"逐参数",参数右键菜单提供 "Enable for control" 开关,受控参数带绿色控制器图标;
- Phase C(已完成):算子按所在 Section 分组,组头显示嵌套路径(如 "Init / Render Quality"),路径每一段可点击并在图中居中该 Section。
已锁定的架构决策
计划为整个功能锁定了若干关键决策,是理解后续代码的钥匙:
- 列表顺序是推导出来的,不持久化:算子按画布位置排序(自上而下、再自左而右)。本计划不做持久化排序、不做拖拽重排;如果推导顺序不便,等 Section 拥有成员顺序后再作为后续工作(见 Plan_Sections.md 中关于成员顺序的实现细节)。
- 逐参数启用是"子实例级"的,不是符号级的:现有的
IInputUi.ExcludedFromPresets标志是符号级的(对所有实例生效、用于排除输入),语义不同,保持不变。新标志挂在 SymbolUi.Child 上,作为一组启用的输入 id 集合,序列化进.t3ui的 child 条目中。 - 逐算子标志的向后兼容:
SnapshotGroupIndex == 1且没有逐参数集合的子项,读取语义为"全部参数启用"。图上的右键菜单开关("Enable for snapshots")保留,作为批量开/关便捷入口,一次性设置/清空全部参数。 - 脏检查(dirty check)必须节流/缓存:绝不能每帧朴素地拿每个
InputValue与快照比较。改为在参数变更(命令执行)时重算,外加低频兜底(约每 30 帧),按快照 id 缓存结果。 - 所有变更都走命令:write/revert/remove 以及启停开关必须可撤销(
UndoRedoStack.AddAndExecute)。复用 ChangeSnapshotEnabledCommand 的模式;命令中存 guid,不存实例引用。 - 视觉层级(来自设计草图):视图区背景用
UiColors.WindowBackground级别约 0.5 的淡化,组背景Button.Fade(0.5),输入行Button。只允许使用UiColors.*+.Fade(),禁止字面颜色;所有像素字面量都要乘以T3Ui.UiScaleFactor。 - 控制器图标:需要在
Icon枚举中新增字形(烘焙进图集)。在新增之前,用UiColors.StatusAutomated风格绿色的小实心圆作为可接受的占位,并标记为待替换。
从源码印证:Selection 与脏检查
选择与快照池的解析已经存在于 VariationHandling.cs:
ActivePoolForSnapshots/ActiveInstanceForSnapshots在没有任何子项被选中时,解析到焦点合成(ProjectView.Focused.CompositionInstance);- 库命名空间(
Lib.前缀)的合成会显式把ActivePoolForSnapshots置为null,因此库算子不显示本视图; CreateOrUpdateSnapshotVariation()与AddSnapshotEnabledChildrenToList()按逐算子EnabledForSnapshots遍历。
脏检查实现在 SnapshotControlView.cs 内部的 ModificationCheck 类中:
- 以
(variation.Id, undoStackCount)作为缓存键,CheckIntervalFrames = 30帧为低频兜底; Compute()镜像 Apply 语义:快照中捕获的输入必须与存储值一致;受控算子的其余可混合输入必须处于默认值(因为 Apply 会重置它们);- 比较基于
ValueUtils.BlendMethods/ValueUtils.CompareFunctions注册表,仅对可混合类型逐输入比较;结果缓存进HashSet<(Guid, Guid)> _modifiedInputs,复用缓冲区、避免 LINQ 与每帧分配; - 该缓存同时支撑
IsInputModified(逐行高亮)与IsAnyInputModifiedForChild(组级 revert 按钮启用状态)。
数据模型现状:文件格式已经是逐参数的
计划明确指出 Variation.cs 的 ParameterSetsForChildIds 已经是 childId → inputId → value 的结构,即文件格式今天就是逐参数的;合成输入使用 Guid.Empty 作为 key;States 枚举已包含 Modified。序列化时每个参数条目落盘为 childId 下的 inputId 到 InputValue 的字典,加载逻辑见 TryLoadVariationFromJson。
现有代码基础(what exists)
计划列出了本功能依赖的全部既有代码,作为实现的插桩点:
- Editor/Gui/Interaction/Variations/VariationHandling.cs:
ActivePoolForSnapshots/ActiveInstanceForSnapshots已能在无选中时解析到合成;CreateOrUpdateSnapshotVariation()、AddSnapshotEnabledChildrenToList()按逐算子EnabledForSnapshots遍历。 - Editor/Gui/Interaction/Variations/Model/Variation.cs:
ParameterSetsForChildIds已是childId → inputId → value,文件格式已逐参数;合成输入用Guid.Empty;States已有Modified。 - Editor/Gui/Interaction/Variations/Model/SymbolVariationPool.cs:
Apply、BeginBlendTowardsSnapshot、TryCreateVariationForCompositionInstances、UpdateVariationPropertiesForInstances、DeleteVariation、SaveVariationsToFile。 - Editor/UiModel/SymbolUi.Child.cs:
SnapshotGroupIndex后备字段与EnabledForSnapshots属性;序列化在 Editor/UiModel/SymbolUiJson.cs。 - Editor/UiModel/Commands/Graph/ChangeSnapshotEnabledCommand.cs:可撤销的逐算子开关,是逐参数变体的模式参考(
Do/Undo都走Apply(useNew),存储每个子项变更前的组索引以精确还原)。 - Editor/Gui/Windows/ParameterWindow.cs:
ViewModes枚举(Parameters/Settings/Help);无选中分支当前调用DrawSettingsForSelectedAnnotations()后直接返回——这就是插桩点。静态DrawParameters()渲染可编辑输入行,可复用。 - Editor/Gui/Windows/ParameterSettings.cs:行样式以及(后续)拖拽手柄交互的参考。
- Editor/UiModel/InputsAndTypes/InputValueUi.cs:参数右键菜单(
CustomComponents.ContextMenuForItem),"Enable for control" 的插桩点。 - Editor/Gui/MagGraph/Interaction/GraphContextMenu.cs:逐算子 "Enable for snapshots" 开关(保留,变为批量开关)。
- Editor/Gui/Windows/Variations/VariationsWindow.cs +
SnapshotCanvas.cs:操作同一池的另一个 UI,本视图写入/删除时必须与之保持同步(激活状态、缩略图)。 - 图中居中算子:参考
ProjectView/NodeSelection的 fit-view 处理(现有的 "center on selection" 交互)。
Phase A:逐算子粒度的快照控制视图
状态(2026-06-13):已实现——代码位于 Editor/Gui/Windows/SnapshotControlView.cs,接入 ParameterWindow 的无选中分支。手动测试集见计划引用的 snapshot-control-view.md。控制器图标与逐参数启用留待 Phase B。
Phase A 的目标是:用现有的数据模型让视图可用,不做任何序列化变更。
插桩点:ParameterWindow 的无选中分支
从 ParameterWindow.cs 源码可见实际插桩逻辑:
if (!NodeSelection.TryGetSelectedInstanceOrInput(out var instance, out var inputUi, out _selectionChanged))
{
var nodeSelection = ProjectView.Focused?.NodeSelection;
var sectionSettingsShown = nodeSelection != null && DrawSettingsForSelectedSections(nodeSelection);
if (!sectionSettingsShown
&& VariationHandling.ActivePoolForSnapshots != null
&& !SkillTraining.IsInPlayMode)
{
// 先绘制激活合成的头部(名称/命名空间),再绘制快照控制视图
var composition = ProjectView.Focused?.CompositionInstance;
if (composition != null)
{
if (DrawSymbolHeader(composition, composition.GetSymbolUi()))
composition.GetSymbolUi().FlagAsModified();
}
_snapshotControlView.Draw();
}
...
}
要点:仅当 ActivePoolForSnapshots != null 且不在 SkillQuest 播放模式下才绘制控制视图;每个窗口实例各自维护滚动状态,而快照池是"每个被聚焦合成全局一份"的。
选择器栏
顶部固定选择器栏包含:
- 索引指示器(
ActivationIndex); - 快照下拉框(标题 + 索引,缺省回退为 "Snapshot #n");
- 上一/下一个箭头,按
ActivationIndex顺序循环; - 右侧通过
CustomComponents.RightAlign对齐的 write / revert / remove 图标按钮。Write 与 Revert 仅在脏检查报告已修改时可用;Remove 在选中了快照时始终可用。
关键实现约束:
- Write =
UpdateVariationPropertiesForInstances(既有可撤销路径),而不是"删除 + 重建",从而保住快照的 id 与缩略图位置; - Revert = 对选中快照执行
Apply(已是命令驱动); - 空池 →
CustomComponents.EmptyWindowMessage显示提示 + "create snapshot" 按钮(CreateOrUpdateSnapshotVariation)。
算子列表(本阶段扁平)
列出所有 EnabledForSnapshots 的子项,按画布位置排序(自上而下、自左而右)。每个算子一块:
- 头行:算子名,按类型着色(同图中),点击 → 选中并在图中居中;不可折叠(折叠留给 Phase C 的 Section 组);
- 下方:该快照捕获的输入对应的参数行,用既有
DrawParameters行机制渲染,保证编辑、右键菜单、动画指示器行为一致。
快照中存在但已不再启用(或已删除)的算子 → 显示为弱化的 stale 行,带清理入口(RemoveInstancesFromVariationsCommand 已存在)。
Inputs 组与脏检查
- 若快照包含
Guid.Empty参数集,将合成输入作为标题为 "Inputs" 的组列出。 - 脏检查由一个小型辅助类(如
SnapshotModificationCheck)实现:比较当前实例值与选中快照的InputValue——命令执行时事件驱动重算 + 节流兜底;禁止每帧分配(复用缓冲区、不用 LINQ)。
与 Variations 窗口的同步
write/remove 之后,池的快照列表与 State 标志必须立即反映(两个 UI 读同一个 SymbolVariationPool;需验证 UpdateActiveStateForVariation 路径)。
Phase A 明确不做:分组、重排、逐参数启用。
验证:.tests-manual/ 下的手动测试集(创建/选择/修改/write/revert/remove;每一步都可 undo;检查 Variations 窗口保持一致;检查 Lib. 命名空间合成因 ActivePoolForSnapshots 为 null 而不显示本视图)。
Phase B:逐参数启用
状态(2026-06-13):已实现——SymbolUi.Child.SnapshotEnabledInputIds(null = 全部,兼容旧数据)、ChangeSnapshotEnabledInputsCommand、SymbolVariationPool 中捕获/应用/混合的过滤、通过 VariationHandling.ToggleParameterSnapshotControl 实现的 "Enable for control" 右键菜单开关。控制器指示器:输入连接区的 Icon.Knob 用 UiColors.StatusControlled 着色。视图在 SkillQuest 播放模式下被抑制。
Phase B 的目标:"enabled for snapshots" 成为子实例的逐参数属性。
数据模型
SymbolUi.Child增加序列化的快照启用输入 id 集合(HashSet<Guid>? SnapshotEnabledInputIds)。- 读取端向后兼容:
SnapshotGroupIndex == 1且集合缺失/为空 → 全部输入启用(惰性物化,用户改动前不写入)。 - 写入端:
ParameterCollections(组索引 > 1)的SnapshotGroupIndex保持不动。
从 SymbolUi.Child.cs 源码可以看到完整的语义:
// 0 - not relevant for snapshots
// 1 - used for snapshots (creating a new snapshot will copy the current state of child)
// >1 - used for ParameterCollections
internal int SnapshotGroupIndex { get; set; }
private const int GroupIndexForSnapshots = 1;
public bool EnabledForSnapshots
{
get => GroupIndexForSnapshots == SnapshotGroupIndex;
set => SnapshotGroupIndex = value ? GroupIndexForSnapshots : 0;
}
// Null means all blendable inputs are enabled — the legacy per-op semantics.
// The set is only materialized once the user toggles an individual parameter,
// so untouched files keep their original shape.
internal HashSet<Guid>? SnapshotEnabledInputIds { get; set; }
internal bool IsInputEnabledForSnapshots(Guid inputId)
=> EnabledForSnapshots
&& (SnapshotEnabledInputIds == null || SnapshotEnabledInputIds.Contains(inputId));
internal bool IsInputIncludedForVariation(Guid inputId)
{
if (SnapshotGroupIndex != GroupIndexForSnapshots || SnapshotEnabledInputIds == null)
return true;
return SnapshotEnabledInputIds.Contains(inputId);
}
命令与过滤
- 新增可撤销命令
ChangeSnapshotEnabledInputsCommand(基于 guid,按 AGENT_INSTRUCTIONS.md 的撤销/重做规则做防御性解析)。 VariationHandling/SymbolVariationPool.TryCreateVariationForCompositionInstances按逐参数集合过滤捕获的输入(此前捕获启用算子的全部非默认、非ExcludedFromPresets输入)。- 参数右键菜单(
InputValueUi)新增 "Enable for control" 开关(与 animate / extract / publish-as-input 并列);受控参数在名称旁显示绿色控制器图标(新增Icon枚举字形——需求已提出;此前用占位圆圈)。 - 图右键菜单的逐算子开关变为批量:启用 = 全部参数,禁用 = 清空集合。原有"开关后自动更新快照"的行为扩展到参数级变更。
- 快照控制视图:启用/禁用参数会更新所列行;Phase A 的逐算子 stale 处理覆盖"从控制中移除的参数"。
- 与符号级
ExcludedFromPresets的交互已定案:排除优先,控制视图绝不提供被排除的输入。
验证:扩展手动测试集;重点测试旧 .t3ui 文件(仅逐算子标志)按"全部参数"语义加载,且单纯加载不重写文件。
逐参数操作菜单(2026-06-14)
每个参数行在右侧装订线有一个 …(Icon.Settings2)动作按钮(装订线加宽到两个图标宽)。菜单项:
- Write to snapshot(已修改时可用)
- Write to all snapshots(与任一快照不同时可用——仅在弹窗打开期间比较)
- Reset(恢复默认值)
- 分隔线
- Disable Snapshot control(仅算子;合成
Guid.Empty输入无法通过子 UI 切换)
写入复用 VariationHandling.ApplyParameterToVariations(基于既有 CloneParameterSetsWithValue + UpdateVariationParametersCommand 构建),每次写入是一个可撤销宏。
参数右键菜单中的快照动作(2026-06-14)
快照 write/reset 动作通过 SnapshotControlView.DrawSnapshotActionMenuItems 共享(Write to snapshot、Write to all snapshots、Reset to Snapshot)——一个放在控制视图类中的 static 方法(避免继续膨胀已经很长的 InputValueUi),以私有静态 _activeSnapshotMenuContext(一个 {pool, activeSnapshot, childKey} 记录,视图在 DrawControlledParameters 周围设置、其他位置为 null)为门控。InputValueUi 的右键菜单调用它;IsSnapshotControllable / "Control with Snapshots" 开关仍留在 InputArea。行内齿轮菜单与参数右键菜单都调用它;在右键菜单中,它们位于新的 "Snapshot control" 组标签下(紧挨 "Control with Snapshots")。"Reset" 被重新命名为 "Reset to Default",以区别于 "Reset to Snapshot"(revert 图标的菜单形式)。对合成 Guid.Empty 输入,快照查找使用上下文的 ChildKey,而 reset-to-snapshot 命令使用作用域内的 compositionSymbol / symbolChildUi.Id——二者一致,因为合成的输入存在它自己的池的 Guid.Empty 键下。
菜单与导航精修(2026-06-14)
CustomComponents.DrawMenuItem增加了reserveCheckmarkColumn——快照菜单(选择器栏 + 逐参数)没有开关项,因此去掉复选标记列、整体左移。- 双击选择器触发可重命名激活快照(
VariationPicker.Draw通过out renameRequested报告;第一次点击时短暂打开的弹窗会在重命名模式替换选择器后关闭)。 - 左/右箭头循环切换快照、Enter 重命名激活快照——前提是参数窗口持有焦点(
IsWindowFocused(RootAndChildWindows),以!IsAnyItemActive && !WantTextInput为门控),窗口周围绘制共享的焦点框。Enter 重命名无冲突,因为视图只在图中无选中时显示(此时图自身的 Enter 重命名是惰性的)。选择器栏箭头的 tooltip 提示快捷键。
从 SnapshotControlView.cs 源码可见键盘导航实现:HandleSnapshotKeyboardNav 检查窗口焦点后绘制焦点框,在无活动项/无文本输入请求时响应 Left/Right/Enter 键。
Phase C:Section 分组
状态(2026-07-05):已实现——算子列表消费 SectionTree.Build(其第一个消费者),通过扁平化的行列表(DisplayRow)呈现,在撤销栈/Section 数/算子数变化时重建,外加 30 帧兜底(与 ModificationCheck 相同的节流惯用法)。
与初版范围的设计偏差
- 路径头按最初草图实现("TEST01 / SUBSECTION"),小号弱化全大写、无缩进——先试过缩进树变体但占用行宽过多。每个 Section 只为一个直接包含快照启用算子的组出头;没有直接算子的 Section 不出头、其名字只出现在后代的路径里;子树中没有任何快照启用算子的 Section 整体跳过。
- 折叠状态按窗口实例(视图内的
HashSet<Guid>),不序列化,与图中框架的折叠状态相互独立。折叠只隐藏组自己的算子——嵌套组保留自己的头和状态。 - 组头工具右对齐:Aim 图标通过
IGraphView.OpenAndFocusSection居中框架(无选择——选中Section会把参数窗口切到 Section 设置);Reset 图标将该组自己的算子回退到快照(一个宏;通过脏缓存的IsAnyInputModifiedForChild启用)。 - 折叠图框架里隐藏的算子仍会列出;点击其名称跳到折叠框架(
HiddenInCollapsedSectionId),而不是选中不可见算子。 - "Ungrouped" 桶(伪头,
Guid.Empty折叠键)只在至少有一个真实组时出现;没有 Section 时列表保持扁平如旧。 - 排序切换为自顶向下/自左向右(升序),组与算子一致,匹配
SectionTree的成员顺序——废弃了之前"从右下开始"的排序实验。 - 拖拽重排(额外目标)未做——Section 仍未拥有持久化的成员顺序。
名称点击回退到快照(2026-07-05)
在控制视图中,点击参数名现在回退到激活快照的值(行高亮所比较的对象),而不是默认值——SnapshotControlView.TryResetParameterToSnapshot,挂进 InputValueUi 的名称点击,以同一个 _activeSnapshotMenuContext 门控;悬停提示/revert 图标跟随(IsResetToSnapshotActive + DimHighlightOverride),仅当该行与快照不同时显示,值匹配时为无操作(不产生 undo 条目)。这使行内 revert 图标冗余,因此连同其拖拽缩放的无限滑条(HandleRevertHandle)一起移除——右侧装订线回到单个图标(… 动作菜单),节省行宽。"Reset to Snapshot" 仍保留在菜单中。
目标与范围回顾
- 消费 Section 计划中构建的 section 树辅助——绝不在本地几何推导成员归属。
- 组头:每个算子的最内层 Section;头部显示嵌套路径("Init / Render Quality");每段可点击 → 在图中居中该 Section。无 Section 的算子落入底部 "Ungrouped";合成输入保持顶部 "Inputs" 组。
- 组可折叠(折叠状态按窗口实例、不序列化)。组级 revert 按钮:仅对该组算子的快照值重新应用,组内任一参数脏时启用(复用脏检查缓存)。
- 组顺序由 Section 画布位置推导。通过拖拽手柄(
ParameterSettings模式)手动重排组/算子为额外目标,仅在 Section 拥有持久化成员顺序之后才考虑。 - 折叠 Section 中隐藏的算子仍出现;点击会展开/居中到折叠框架。
控制器索引网格(Controller-index grid)
点击选择器下拉框左侧的索引会打开一个启动台风格的激活索引网格,让 MIDI 索引布局显式化、并与列表的显示顺序区分开,解决"索引 vs 顺序"的混淆。
已完成的细节(2026-06-14 起逐项落地)
- 网格视图(
DrawControllerGrid):点击应用、悬停预览(以VariationHoverPreview为门控)+ 标题 tooltip。 - 可插拔布局:ControllerGridLayout 将屏幕单元格映射为激活索引;
CompatibleMidiDevice.GridLayout让每个控制器提供自己的排布(它已经知道这个映射以驱动 LED 颜色——ApcMini返回自下而上的 8×8)。ControllerGridLayouts.All收集它们(对设备扫描做反射),外加内置的 "Reading order"(自上而下),现在是默认——修正了反直觉的自下而上。 - APC 差一(off-by-one)修复:APC 布局是 0 基的(原始 pad note,
(7-row)*8 + col,无+1):APC 的 pads 是 note 0–63,ButtonRange.GetMappedIndex返回note - startIndex(= note 本身),因此 pad 激活的快照索引等于其 note。此前的+ 1让每个单元格在硬件上偏移一个 pad。(Reading order 保持 1 基/自然序;单元格标签永远是它所代表的激活索引。) - 拖拽重指派索引:拖拽已填充单元格通过 ChangeVariationActivationIndexCommand 重指派其
ActivationIndex:放到空闲槽位是 move,放到已占用槽位是 swap(占用者拿到被拖单元格的旧索引——绝不允许两个快照占同一个 pad)。拖拽手动跟踪(_gridDragSourceId+ 鼠标悬停单元格命中测试),不走 ImGui 的 payload API;源单元格通过 scrim 变暗(对激活与非激活单元格统一——alpha 淡化颜色会让弱化单元格消失),目标描边,光标 chip 携带索引和名称。悬停预览/tooltip/点击应用在拖拽期间暂停;在源上或外部释放为无操作。 - 头部与悬停打磨:网格头部标题用
FontNormal,垂直居中于下拉行,布局下拉框右侧有DocumentationButton。算子块悬停(EndBlock)现在以ImGui.IsWindowHovered为门控,这样打开的弹窗(网格、选择器、动作菜单)不再把悬停泄漏到其后的面板上——单独的IsMouseHoveringRect是纯几何测试,会忽略盖在上方的弹窗。 - 抽取为独立类:整个弹窗现在位于 SnapshotControllerGrid(自己的弹窗 id、布局/预览/拖拽状态与辅助方法)。
SnapshotControlView从索引标签调用_controllerGrid.Open(pos),每帧调用_controllerGrid.Draw(pool, composition, active, snapshots),点击到快照则应用返回结果。 - 指引与帮助:标题改为 "Edit controller index";填充单元格显示手型光标(拖拽时携带)提示可拖拽重指派。Doc 按钮靠右(手动光标 X——
RightAlign会额外缩进一个窗口 padding)。Doc 按钮指向聚焦的 .help/embedded/ControllerIndex.md("what is this panel"),而不是宽泛的 Variations 片段。 - 单元格颜色镜像 APC:填充单元格为绿色(
StatusControlled——那里有一个可控快照;静止.Fade(0.7f)、悬停全亮),激活/实时单元格为品红(StatusAttention),匹配 APC Mini 的绿色已用/热点激活 LED,并保持 "green = controlled" 语义(网格曾是唯一把激活单元格画成绿色的地方;Variations 窗口已用橙色WidgetActiveLine圆点标记激活)。拖放目标描边切换为ForegroundFull,以便在绿色单元格上可读。填充单元格用ResizeAll(移动)光标而非指点手型,表示可拖拽。 - 索引按钮:选择器栏索引现在是圆角按钮(悬停点亮),显示补零索引,tooltip "Click to edit MIDI controller indices"。
UpdateCachedLabels也以ActivationIndex为键,因此网格中重指派激活快照的索引会刷新按钮标签(此前只按 id/标题缓存)。 +始终可用:创建快照的+现在始终可点击——常态为Default状态,激活快照有未保存修改时变Emphasized(此前是"未修改则禁用")。- 栏 Write、菜单 Revert:选择器栏图标改为 Write(
Icon.Apply,已修改时强调 →WriteSnapshot);Revert 移入动作菜单(Icon.Reset→ 重新应用快照)。旧的栏内 revert 无限滑条(DrawBarRevertButton+_barRevert*)被移除——用户从未使用拖拽缩放;行内 revert 图标(含滑条)不动。 - 在激活快照之后插入:在已有激活快照时创建新快照,新快照取得其上的下一个空闲控制器索引(
SymbolVariationPool.GetNextFreeActivationIndexAfter,忽略刚创建的 variation),并插入到画布上激活快照之后且无重叠/空隙:InsertSnapshotBehind先停在下一个空闲槽,再按 reading order 冒泡回插——每次交换把后一个快照往后移一个槽(选择器的重排机制)。Reading-order 排序抽取为共享的VariationBaseCanvas.SortByReadingOrder(选择器复用)。无激活快照/显式 MIDI 槽时仍用FindFreePositionForNewThumbnail。(Undo 注意:位置偏移在撤销创建时不会回退——创建时的位置从未有命令支撑——因此列表中间插入 + undo 会留下一个槽位空隙;仅在激活的并非最后一个时才有影响。) - 设置菜单 + 缩略图单元格:头部新增
Settings2齿轮(doc 按钮左侧)打开设置弹窗;布局/设备选择从头部下拉框移入这里(可勾选列表),另有 Show thumbnails 开关。开启缩略图后,单元格绘制快照缩略图(经ThumbnailManager),绿色/品红状态移到单元格边框,索引放在深色底上保证可读。_showThumbnails仅本次会话有效。 - 布局持久化:所选布局按名称保存在
UserSettings.Config.SnapshotControllerLayout(反射构建的ControllerGridLayouts.All索引跨运行不稳定);ResolveLayoutIndex映射回来,缺省回退到第一个("Reading order")。选择时UserSettings.Save()。 - 已推迟:缩略图开关偏好持久化(仅会话),以及非 APC 控制器的按设备布局。
- 统一快照顺序(2026-06-16):放弃了独立的画布位置 "reading order" 作为排序源——快照现在在所有列出它们的地方(选择器、modulo 激活、
BlendSnapshotsordinal 模式)都按ActivationIndex排序,通过重命名的VariationBaseCanvas.SortByActivationIndex,使列表、控制器网格与 MIDI pads 共享同一顺序。选择器拖拽重排现在交换ActivationIndex(SwapActivationIndices),通过新命令ModifyVariationIndicesCommand提交(对索引镜像ModifyCanvasElementsCommand)。激活后插入简化为仅GetNextFreeActivationIndexAfter——单靠索引即可定位,因此InsertSnapshotBehind的PosOnCanvas冒泡逻辑被移除(上面的 undo 注意也随之消失)。Variations 窗口的 2D 画布仍保留自由的PosOnCanvas放置用于 Alt-拖拽空间混合——只改了排序源,没改画布。
未决问题(Open questions)
计划保留了三个开放性决策,均在视图被验证后再定:
- 当合成有已发布输入时,快照控制视图是否也替换常规的无选中状态("整个视图可以是参数窗口"的想法)?推迟到视图证明自己之后——这会改变所有用户对"nothing selected"的定义。
- 上一/下一个箭头:按
ActivationIndex循环还是按池中的列表顺序?(提案假设按激活索引;空隙跳过。) - 混合(blend)激活期间执行 "write" 是否应提交混合后的状态?可能应该(它等于当前值),但需对照
BlendActions.SmoothVariationBlending验证。
文档与后续
计划要求随 Phase A 的同一 PR 在 .help/using/ 下为快照/控制视图新增页面或章节,并在 Phase B、C 中扩展。整体实现目前散布在 SnapshotControlView.cs(1400 余行,含选择器栏、算子/分组列表、脏检查缓存、键盘导航、共享快照菜单)、SnapshotControllerGrid.cs(控制器索引网格弹窗)与 ParameterWindow.cs(无选中分支插桩)中,可结合 Plan_VariationPicker.md 与 Plan_Sections.md 继续追踪选择器与分组结构的演进。