输入与显示事件 API

基本信息

属性 值
包 me.eigenraven.lwjgl3ify.api
声明位置 gradle.properties 的 apiPackage = api（与 modGroup = me.eigenraven.lwjgl3ify 合成）
本条目覆盖的类型 6（InputEvents、DisplayEvents、DisplayWindowContext、SwapchainInvalidatingChange、FloatMouseHelper、GLCapabilitiesOverride）
已知外部使用者 ModularUI2

me.eigenraven.lwjgl3ify.api 是 LWJGL3ify 唯一对外承诺稳定的包（apiPackage = api，gradle.properties:105），供其他 mod 订阅原始 LWJGL3 输入与窗口生命周期事件。

功能

InputEvents

InputEvents.java:16 — 原始键盘/文本事件总线。

嵌套类型：

类型 位置 内容
enum KeyAction :19 按键动作
class KeyEvent :26 字段：lwjgl2KeyCode（:32）、lwjgl2ScanCode（:32）、sdlKeyCode（:37）、sdlScanCode（:37）、sdlRawKeyCode（:42）、action（:44）、sdlKeyModifiers（:46，short）、keyNamePointer（:51，long）
class TextEvent :68 单一 public final String text（:71）
interface KeyboardListener :83 两个 default 方法：onKeyEvent(KeyEvent)（:86）、onTextEvent(TextEvent)（:89）

关键设计：每个 KeyEvent 同时携带 LWJGL2 与 SDL 两套编码（lwjgl2KeyCode / sdlKeyCode 等）。这让下游 mod 无需自己转换即可按需选择编码。

注册方法（静态）：

方法 位置 语义
addKeyboardListener(KeyboardListener) :96 强引用持有
removeKeyboardListener(KeyboardListener) :101 移除强引用监听器
addWeakKeyboardListener(KeyboardListener) :109 仅持 WeakReference，被 GC 后自动清理
removeWeakKeyboardListener(KeyboardListener) :114 提前移除弱引用监听器
injectKeyEvent(KeyEvent) :125 合成按键事件分发给所有监听器

底层用两个 ArrayList：keyboardListeners（:92）与 weakKeyboardListeners（:93）。

injectKeyEvent 的分发顺序（:126-140+）：先把事件投递给 Minecraft.getMinecraft().currentScreen——若当前 GUI 实现了 KeyboardListener 就直接回调（:126-129）；再遍历强引用列表（:130-133）；再遍历弱引用列表，遇到已被回收的引用时就地移除并把索引 i--（:134-140）。

TextEvent 有对应的合成入口吗？本次核验中未见 injectTextEvent 静态方法——TextEvent 仅在 onTextEvent 回调参数中出现。该缺口标记为无法核实是否有其他派发路径。

DisplayEvents

DisplayEvents.java:9 — 窗口与 GL 上下文生命周期事件。

方法 位置 语义
setCreateGLContext(boolean) :18 开关是否创建 GL 上下文
isCreateGLContextEnabled() :22 查询上一项
addPreWindowCreateListener(Consumer<DisplayWindowContext>) :26 窗口创建前
addPostWindowCreateListener(Consumer<DisplayWindowContext>) :30 窗口创建后
addPreSwapchainInvalidatingChangeListener(Consumer<SwapchainInvalidatingChange>) :38 交换链失效前
firePreWindowCreate(ctx) :42 触发
firePostWindowCreate(ctx) :46 触发
firePreSwapchainInvalidatingChange(change) :50 触发

DisplayWindowContext（DisplayWindowContext.java:11）是 Java record，字段 int props, long window, long glContext, PixelFormat pixelFormat, ...（:11）。

SwapchainInvalidatingChange（SwapchainInvalidatingChange.java:16）同样是 record：Kind kind, boolean newFullscreen, @Nullable DisplayMode newMode（:16），其内嵌 enum Kind 在 :18。

FloatMouseHelper

FloatMouseHelper.java:6 — 单方法接口，供 MixinMouseHelper 实现（见 SDL 输入与窗口 Mixin）。让鼠标移动以浮点像素传递，替代 1.7.10 的整数像素。

GLCapabilitiesOverride

GLCapabilitiesOverride.java:13 — final 类，提供 static void set(Set<String>)（:18）与 static Set<String> get()（:25），用于覆盖 GL 能力集名称。

数值

数值 值
InputEvents.KeyEvent 的 public final 字段数 8
同时携带的编码体系 2（LWJGL2 + SDL）
键盘监听器注册方法数 4
合成事件注入方法数 1（injectKeyEvent）
DisplayEvents 的 listener 注册方法数 3
DisplayEvents 的 fire 方法数 3
本包内 record 数 2（DisplayWindowContext、SwapchainInvalidatingChange）

已知静默失败点

DisplayEvents.fire(ArrayList<Consumer<T>>, T)（DisplayEvents.java:54-63）对每个监听器包一层 catch (Throwable t)，只打 Lwjgl3ify.LOG.error("Display event listener error", t)（:59-61）。

后果：某个第三方监听器抛异常时，异常被记录但不影响其余监听器被调用，且调用方（窗口创建/交换链切换路径）不会感知失败继续执行。异常本身未被静默——有 ERROR 级日志——但失败被隔离。

交互

触发 行为
其他 mod 调 InputEvents.addKeyboardListener 之后每次 LWJGL3 原始按键都会回调其 onKeyEvent
当前打开的 GUI 实现 KeyboardListener 额外收到一次回调（早于注册列表）
监听器被 GC（弱引用） 下次派发时自动从列表移除
窗口创建 / 交换链切换 触发 DisplayEvents 的 pre/post 回调
某个 DisplayEvents 监听器抛异常 记 ERROR，其余监听器继续

相关条目