Rowland/EG

Fork 1

Rowland 8e604545f4 first commit

2025-07-02 09:49:59 +08:00

5.0 KiB

Raw Blame History

GUI预览窗口使用说明

概述

GUI预览窗口是一个独立的Panda3D窗口，专门用于正确显示2D GUI元素，解决Qt集成中DirectGUI显示的问题。

主要特性

✅ 解决的问题

2D GUI显示问题: 在Qt集成的主窗口中，DirectGUI元素可能无法正确显示
独立渲染环境: 提供纯Panda3D环境，确保GUI元素正确渲染
实时同步: 自动与主程序中的GUI元素保持同步

🚀 核心功能

独立窗口: 完全独立的Panda3D窗口，不受Qt影响
自动同步: 每0.5秒自动检测主程序GUI元素变化
支持所有GUI类型: 按钮、标签、输入框、滑块、3D文本、虚拟屏幕
交互预览: 在预览窗口中可以真实地与GUI元素交互

使用方式

1. 在主程序中使用

from gui_preview_window import GUIPreviewWindow

# 创建预览窗口
preview = GUIPreviewWindow()

# 连接到主程序world对象
preview.set_main_world(your_world_object)

# 预览窗口会自动同步显示GUI元素

2. 通过GUI编辑模式

在主程序中点击菜单："GUI" → "进入GUI编辑模式"
预览窗口会自动弹出
使用主程序的工具栏创建GUI元素
在预览窗口中实时查看效果

3. 工具栏快速创建

主程序提供了便捷的工具栏按钮：

创建按钮: 在场景中创建可点击按钮
创建标签: 创建文本标签
3D文本: 创建3D空间文本

支持的GUI元素类型

2D GUI元素 (DirectGUI)

类型	说明	在预览窗口中的表现
按钮	DirectButton	完全可交互，支持点击
标签	DirectLabel	正确显示文本内容
输入框	DirectEntry	支持文本输入和提交
滑块	DirectSlider	支持值调整交互

3D GUI元素

类型	说明	在预览窗口中的表现
3D文本	TextNode	3D空间中的文本，支持广告牌效果
虚拟屏幕	CardMaker + TextNode	带背景的虚拟显示屏

技术实现

自动同步机制

def sync_with_main(self, task):
    """每0.5秒检测GUI元素变化"""
    if self.main_world and hasattr(self.main_world, 'gui_elements'):
        main_count = len(self.main_world.gui_elements)
        preview_count = len(self.gui_elements)
        
        if main_count != preview_count:
            self.refresh_all_gui()  # 自动刷新
    
    return task.again

窗口配置

loadPrcFileData("", """
    win-size 800 600
    window-title GUI预览窗口 - 2D GUI专用显示
    framebuffer-multisample 1
    multisamples 2
    audio-library-name null
    notify-level-audio error
""")

操作说明

鼠标控制

滚轮: 缩放视图
右键拖拽: 旋转视角 (未来版本)

状态显示

预览窗口底部会显示当前状态：

"等待GUI元素..." - 尚未同步到任何GUI
"已同步 N 个GUI元素" - 正在显示N个GUI元素

优势对比

与嵌入式方案对比

特性	独立预览窗口	Qt嵌入式
2D GUI显示	✅ 完美支持	❌ 显示问题
性能	✅ 原生性能	⚠️ 集成开销
交互性	✅ 完全交互	⚠️ 部分限制
开发复杂度	✅ 简单	❌ 复杂

与独立编辑器对比

特性	预览窗口	独立编辑器
操作流程	✅ 简化	❌ 复杂
学习成本	✅ 低	❌ 高
实时性	✅ 自动同步	⚠️ 手动刷新
代码维护	✅ 简单	❌ 复杂

故障排除

常见问题

Q: 预览窗口没有显示GUI元素 A: 检查是否正确连接到主程序world对象，确保调用了set_main_world()

Q: GUI元素显示位置不正确 A: 2D GUI使用屏幕坐标系，3D GUI使用世界坐标系，检查创建时的坐标参数

Q: 预览窗口无法交互 A: 确保预览窗口有焦点，尝试点击窗口使其获得焦点

调试信息

预览窗口会在控制台输出详细的调试信息：

✓ GUI预览窗口已创建 - 专用于显示2D GUI元素
预览窗口已连接到主程序
检测到GUI元素变化: 主程序1个, 预览0个
预览窗口创建元素: button - 测试按钮

未来扩展

计划功能

预览窗口中直接编辑GUI属性
鼠标右键拖拽旋转视角
GUI元素高亮和选择
布局网格显示
多视角预览（正交、透视）

API扩展

# 未来可能的API
preview.set_view_mode("orthographic")  # 设置正交视图
preview.enable_grid(True)              # 显示网格
preview.highlight_element(gui_element) # 高亮元素

总结

GUI预览窗口提供了一个简洁高效的解决方案，让开发者能够：

在主程序中直接编辑 - 不需要额外的编辑器窗口
在独立窗口中预览 - 确保GUI元素正确显示
实时同步更新 - 无需手动刷新，自动保持同步

这种设计大大简化了GUI开发流程，同时解决了Qt集成中的显示问题。

5.0 KiB Raw Blame History Unescape Escape