window-axis-innovators-box1.17/api-documentation/events/Axis Innovators Box 事件类集合技术文档.md

Axis Innovators Box 事件类集合技术文档

包路径: com.axis.innovators.box.events.*
主要功能: 作为事件总线（EventBus）的载体，定义系统各模块间的通信数据结构
作者: tzdwindows 7

---

1. 概述

本篇文档总结了 Axis Innovators Box 框架中定义的核心事件类。这些类作为 EventBus 分发的数据负载（Payload），涵盖了应用程序生命周期、UI 渲染、用户交互及系统设置等多个维度。

框架采用了 Java Records (JDK 16+) 和 常规 POJO 混合编写的方式：

• Records: 用于纯数据传输，简洁高效。
• Classes: 用于需要逻辑处理或可变状态（如事件拦截）的复杂场景。

---

2. 核心事件分类详解

2.1 系统生命周期事件

StartupEvent (Record)

• 触发时机: 应用程序启动阶段。
• 用途: 允许插件或子模块在系统就绪时获取主程序实例并执行初始化。
• 字段:
  • AxisInnovatorsBox main: 主程序入口实例。

---

2.2 主窗口与 UI 交互事件

MainWindowEvents (Container Class)

内部包含两个核心 Record，用于处理主窗口的不同阶段：

• initialize (Record):
  • 触发时机: 主窗口初始化加载时。
  • 用途: 向主面板 (mainPanel) 添加自定义组件。
• update (Record):
  • 触发时机: 窗口重绘或更新周期。
  • 用途: 执行基于 Graphics 的自定义绘制逻辑。

TABUIEvents (Class)

• 用途: 管理选项卡（Tab）组件的 UI 属性设置。
• 内部类 update: 专门用于选项卡的重绘事件，传递 Graphics 上下文。

TopicsUpdateEvents (Class)

• 触发时机: 当系统主题发生变更（如切换深色模式/更换皮肤）时。
• 用途: 通知所有 UI 组件同步更新样式。
• 字段:
  • String themeName: 主题名称。
  • boolean darkTheme: 是否为暗黑模式。

---

2.3 文件与 IO 操作事件

OpenFileEvents (Class)

• 触发时机: 当程序接收到外部文件打开请求（如拖拽文件入窗口）时。
• 核心功能: 流程控制。
• 关键字段:
  • File filePath: 文件路径。
  • String extension: 文件后缀名。
  • boolean isContinue: 默认值为 true。监听器可以通过 setContinue(false) 来拦截后续操作，阻止程序打开该文件。

---

2.4 设置与配置事件

SettingsLoadEvents (Record)

• 触发时机: 设置对话框加载时。
• 用途: 动态扩展设置界面。开发者可以获取 JPanel content 容器，向其中注入新的设置项（如复选框、输入框）。
• 字段:
  • WindowsJDialog dialog: 设置窗口实例。
  • JPanel content: 承载设置内容的容器面板。

---

3. 事件一览表

事件类名	类型	核心字段	应用场景
StartupEvent	Record	main	插件初始化、全局资源准备
MainWindowEvents.initialize	Record	mainWindow, mainPanel	注入主界面组件
MainWindowEvents.update	Record	mainWindow, g	自定义画布渲染
OpenFileEvents	Class	filePath, isContinue	文件打开监听、格式校验与拦截
SettingsLoadEvents	Record	dialog, content	动态添加设置选项
TABUIEvents	Class	javax, card	选项卡组件管理
TopicsUpdateEvents	Class	themeName, darkTheme	皮肤切换、实时调色板更新

---

4. 使用代码示例

示例 1：拦截特定格式的文件打开

@SubscribeEvent
public void onFileOpen(OpenFileEvents event) {
    if (event.getExtension().equalsIgnoreCase("tmp")) {
        System.out.println("拒绝打开临时文件");
        event.setContinue(false); // 拦截流程
    }
}

示例 2：在系统启动时注册组件

@SubscribeEvent
public void onStartup(StartupEvent event) {
    System.out.println("Axis Innovators Box 已启动: " + event.main().getClass().getName());
}

示例 3：动态添加设置项

@SubscribeEvent
public void onSettingsLoad(SettingsLoadEvents event) {
    event.content().add(new JButton("扩展插件设置"));
}

---

文档生成时间: 2026-01-02