# GUI编辑模式使用指南

## 概述

主程序现在集成了完整的GUI编辑模式，基于 `test_qt_showbase.py` 中验证有效的方法实现。这个功能允许你在3D场景中轻松创建、编辑和管理各种GUI元素。

## 功能特点

### ✨ 核心功能
- **可视化GUI编辑**: 右侧浮动面板提供直观的工具选择
- **多种GUI类型**: 支持2D和3D GUI元素
- **实时预览**: 即时查看创建的GUI效果
- **属性编辑**: 通过属性面板编辑GUI元素属性
- **场景集成**: GUI元素与3D场景完美融合

### 🎯 支持的GUI类型

#### 2D GUI元素
1. **按钮 (Button)**: 可点击的2D按钮
2. **标签 (Label)**: 显示文本信息的标签
3. **输入框 (Entry)**: 用户可输入文本的输入框

#### 3D GUI元素
1. **3D文本**: 在3D空间中显示的文本，支持广告牌效果
2. **虚拟屏幕**: 3D空间中的虚拟显示屏

## 使用方法

### 🚀 启动GUI编辑模式

#### 方法1: 通过菜单
1. 启动主程序 `python3 test.py`
2. 点击菜单栏 `GUI` -> `进入GUI编辑模式`
3. 右侧将出现GUI编辑面板

#### 方法2: 运行测试程序
```bash
cd /home/hello/eg
python3 test_gui_edit_mode.py
```

### 🎨 创建GUI元素

#### 步骤1: 选择工具
在右侧GUI编辑面板中：
- 点击 `按钮` - 创建2D按钮
- 点击 `标签` - 创建2D标签
- 点击 `输入框` - 创建2D输入框
- 点击 `3D文本` - 创建3D文本
- 点击 `虚拟屏幕` - 创建3D虚拟屏幕

#### 步骤2: 放置元素
选择工具后：
1. 在3D场景中点击鼠标左键
2. GUI元素将在点击位置创建
3. 新创建的元素会自动选中并显示在层级树中

### 📝 编辑GUI元素

#### 选择元素
- **方法1**: 在GUI编辑模式下直接点击GUI元素
- **方法2**: 在左侧层级树中点击GUI元素

#### 编辑属性
选中GUI元素后，右侧属性面板会显示可编辑的属性：

**通用属性**:
- 名称
- 位置 (X, Y, Z)
- 缩放

**特定属性**:
- **文本类元素**: 可编辑显示文本
- **2D元素**: 屏幕坐标和实际坐标
- **3D元素**: 世界坐标和旋转

### 🔧 管理GUI元素

#### 删除元素
1. 选中要删除的GUI元素
2. 点击GUI编辑面板中的 `删除` 按钮
3. 或在层级树中右键选择 `删除GUI元素`

#### 复制元素
1. 选中要复制的GUI元素
2. 点击GUI编辑面板中的 `复制` 按钮
3. 或在层级树中右键选择 `复制`

#### 在层级树中查看
- 所有GUI元素显示在 `场景` -> `GUI元素` 节点下
- 显示格式: `类型: 文本内容`
- 支持右键菜单操作

### 🎮 交互控制

#### 鼠标操作
- **左键点击**: 选择GUI元素或创建新元素
- **右键拖拽**: 移动选中的GUI元素 (仅3D元素)
- **中键拖拽**: Z轴移动 (仅3D元素)

#### 键盘快捷键
- **Delete**: 删除选中的GUI元素
- **ESC**: 退出GUI编辑模式 (测试程序)

### 💾 保存和加载

#### 保存项目
GUI元素会随项目一起保存：
1. `文件` -> `保存`
2. GUI元素信息保存在BAM场景文件中

#### 加载项目
加载项目时GUI元素会自动恢复：
1. `文件` -> `打开`
2. 选择包含GUI的项目文件夹

## 坐标系统说明

### 2D GUI坐标
- **屏幕坐标系**: 范围 -1 到 1
- **逻辑坐标**: 用户友好的坐标，自动转换为屏幕坐标
- **转换公式**: `屏幕坐标 = 逻辑坐标 × 0.1`

### 3D GUI坐标
- **世界坐标系**: 与3D场景使用相同的坐标系
- **支持完整的3D变换**: 位置、旋转、缩放

## 技术实现细节

### 基于验证有效的方法
- 使用 `test_qt_showbase.py` 中验证的GUI创建逻辑
- 确保在Qt集成环境中的稳定性
- 统一的错误处理和调试输出

### 关键组件
```python
# GUI编辑模式状态
self.guiEditMode = False
self.guiEditPanel = None
self.currentGUITool = None

# GUI创建方法 (基于test_qt_showbase.py)
def createGUIButton(pos, text, size)
def createGUILabel(pos, text, size)
def createGUIEntry(pos, placeholder, size)
def createGUI3DText(pos, text, size)
def createGUIVirtualScreen(pos, size, text)
```

### 事件处理
- 鼠标事件优先处理GUI编辑模式
- 碰撞检测用于GUI元素选择
- 树形控件与场景实时同步

## 常见问题解答

### Q: GUI元素创建后看不到？
**A**: 检查以下几点：
1. 确保已进入GUI编辑模式
2. 检查创建位置是否在视野范围内
3. 查看控制台输出确认创建成功

### Q: 如何调整GUI元素大小？
**A**: 
1. 选中GUI元素
2. 在属性面板中修改 `缩放` 属性
3. 或通过代码设置: `element.setScale(new_scale)`

### Q: 2D GUI元素位置不准确？
**A**: 
- 2D GUI使用屏幕坐标系
- 在属性面板中查看 `实际屏幕坐标`
- 使用 `逻辑坐标` 进行编辑更容易

### Q: 中文字体显示问题？
**A**: 
- 程序会自动尝试加载系统中文字体
- 如果中文显示异常，检查系统是否安装了中文字体包
- 支持的字体路径: `/usr/share/fonts/truetype/wqy/`

### Q: 如何扩展新的GUI类型？
**A**: 
1. 在 `MyWorld` 类中添加新的创建方法
2. 在 `createGUIEditPanel()` 中添加对应按钮
3. 在 `createGUIAtPosition()` 中添加处理逻辑

## 示例代码

### 程序化创建GUI元素
```python
# 创建按钮
button = world.createGUIButton((0, 0, 5), "我的按钮", 0.1)

# 创建3D文本
text3d = world.createGUI3DText((0, 5, 2), "3D文本", 0.5)

# 创建虚拟屏幕
screen = world.createGUIVirtualScreen((3, 8, 0), (2, 1), "信息显示")
```

### 编辑GUI属性
```python
# 修改文本
world.editGUIElement(gui_element, "text", "新文本")

# 修改位置
world.editGUIElement(gui_element, "position", [x, y, z])

# 修改缩放
world.editGUIElement(gui_element, "scale", 1.5)
```

## 未来扩展

### 计划功能
- [ ] 更多GUI组件类型 (滑块、复选框等)
- [ ] GUI动画系统
- [ ] 主题和样式编辑器
- [ ] GUI模板系统
- [ ] 导出为独立GUI文件

### 贡献指南
如需添加新功能或修复问题：
1. 参考现有的GUI创建方法
2. 保持与 `test_qt_showbase.py` 验证逻辑的一致性
3. 添加适当的错误处理和调试输出
4. 更新文档和使用示例

---

*最后更新: 2024年*