公开 API

基本信息

属性 值
入口类 com.blamejared.controlling.api.ControllingApi
入口类形态 final 类，私有构造函数（纯静态工具类，无法实例化）
公开方法 5 个静态方法
枚举 com.blamejared.controlling.api.ComboModifier（4 值）
兼容层 ControllingApi → ComboKeyBinding → KeyModifier

功能

因为本 mod 通过 Mixin 让所有 KeyBinding（含其他 mod 注册的）都实现了 ComboKeyBinding， 其他 mod 可以直接读写任意按键的组合修饰键，而不必与 mixins.controlling.early 之外的内部类耦合。

API 用独立的 ComboModifier 枚举而不是直接暴露内部的 KeyModifier， 作为对外的稳定表示层。

ComboModifier —— 对外枚举（4 值）

枚举值 映射到内部 说明
NONE KeyModifier.NONE 无修饰键，即裸键绑定
CONTROL KeyModifier.CONTROL Ctrl
SHIFT KeyModifier.SHIFT Shift
ALT KeyModifier.ALT Alt
  • toInternal()：本值 → KeyModifier
  • fromInternal(KeyModifier internal)：内部值 → ComboModifier；internal 为 null 时返回 NONE， 其余按四个分支一一映射

取值与 修饰键枚举 完全一致，不存在 API 独有的状态。

方法详解

supportsComboKeyBinding(KeyBinding) → boolean

返回 keyBinding instanceof ComboKeyBinding。

由于本 mod 用 Mixin 改写了原版 KeyBinding，理论上所有 KeyBinding 都满足该判定； 但该方法的存在让调用方无需硬依赖 ComboKeyBinding 类型即可安全探测。

getComboModifier(KeyBinding) → ComboModifier

返回该按键当前的修饰键。若不是组合键绑定则返回 ComboModifier.NONE（不抛异常）。

getDefaultComboModifier(KeyBinding) → ComboModifier

返回该按键的默认修饰键，同样在不支持时返回 NONE。 与上一个方法的差别决定了 控制设置界面 里"恢复默认"按钮能否点击。

setComboKeyBinding(KeyBinding, ComboModifier, int keyCode) → boolean

同时设置当前修饰键与键码。

步骤 行为
非 ComboKeyBinding 返回 false，不做任何修改
comboModifier == null 归一化为 KeyModifier.NONE
写入 controlling$setKeyModifierAndCode(keyModifier, keyCode)
同步 调用 KeyBinding.resetKeyBindingArrayAndHash()
返回 true

最后一步是必要的：原版把按键按键码分组缓存进 keybindArray，绕过该调用会导致 按键轮询仍使用旧的分组结果。

setDefaultComboKeyBinding(KeyBinding, ComboModifier) → boolean

设置默认修饰键。默认键码仍由原版 KeyBinding.getKeyCodeDefault() 决定， 本方法不涉及键码。

步骤 行为
非 ComboKeyBinding 返回 false
记录 先取 controlling$isSetToDefaultValue() 到 wasDefault
写入 controlling$setDefaultKeyModifier(keyModifier)
条件同步 若 wasDefault 为真，额外调用 controlling$setKeyModifier(keyModifier)
返回 true

最后一步是关键细节：如果该按键当前正处于默认值状态（界面上的"恢复默认"按钮可点， 说明用户没改过它），那么改变默认值时当前值要跟着一起变，否则界面会显示成 "未修改"却与预期默认值不符。反之，若用户已经自定义过，改默认值不会覆盖其当前设置。

错误处理约定

五个方法全部遵循同一约定：不支持组合键时返回 false 或 NONE，绝不抛异常。 comboModifier 传 null 一律按 NONE 处理。调用方可以无条件调用而无需先探测类型。

与内部的对应关系

对外方法 内部接口方法
getComboModifier controlling$getKeyModifier()
getDefaultComboModifier controlling$getDefaultKeyModifier()
setComboKeyBinding controlling$setKeyModifierAndCode(KeyModifier, int)
setDefaultComboKeyBinding controlling$setDefaultKeyModifier(KeyModifier)

另外两个接口方法 controlling$isSetToDefaultValue() 与 controlling$setToDefault() 没有对应的 API 包装方法，只能通过类型判断后直接调用接口。

兼容性约束

Controlling.init 在检测到 mkb（ModernKeybinding）已加载时会直接抛出 IllegalStateException：

“Controlling now ships built-in key combo support and is incompatible with ModernKeybinding (mkb).”

即本 mod 自带组合键支持，与 ModernKeybinding 互斥，两者不能共存。

相关条目