231 lines
6.0 KiB
Markdown
231 lines
6.0 KiB
Markdown
# 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年* |