# 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：拦截特定格式的文件打开
```java
@SubscribeEvent
public void onFileOpen(OpenFileEvents event) {
    if (event.getExtension().equalsIgnoreCase("tmp")) {
        System.out.println("拒绝打开临时文件");
        event.setContinue(false); // 拦截流程
    }
}
```

### 示例 2：在系统启动时注册组件
```java
@SubscribeEvent
public void onStartup(StartupEvent event) {
    System.out.println("Axis Innovators Box 已启动: " + event.main().getClass().getName());
}
```

### 示例 3：动态添加设置项
```java
@SubscribeEvent
public void onSettingsLoad(SettingsLoadEvents event) {
    event.content().add(new JButton("扩展插件设置"));
}
```

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