图形与画布控件

图形类控件用于承载自定义绘制、OpenGL 场景和轻量可视化。Chart 类控件已归入 ChartKit 文档，本章节只说明 WidgetKit 中非图表的图形控件。

控件类型

控件	子内容与能力	典型用途
`UIGQCanvas`	自定义绘制区域、主题背景、鼠标事件承载	标注层、轻量图形区域、状态绘制
`UIGQOpenGLWidget`	OpenGL 初始化、resize、paint、硬件加速渲染	3D 场景、高频图形刷新
`UIGQOGLWidget`	OpenGL 场景封装、兼容渲染区域	工业视图、模型预览、硬件绘制面板

类继承关系

QWidget
  ├─ UIGQCanvas + IUIGQWidgetBase
  └─ QOpenGLWidget
      ├─ UIGQOpenGLWidget + OpenGLFunctions
      └─ UIGQOGLWidget

UIGQCanvas 属于 WidgetKit 主题控件，支持 IUIGQWidgetBase 的主题和布局能力。UIGQOpenGLWidget 与 UIGQOGLWidget 更接近渲染承载控件，继承 Qt OpenGL 体系，重点提供硬件绘制区域。

UIGQCanvas

UIGQCanvas 适合绘制辅助图形、状态标记和轻量的自定义视图。业务可以继承或组合使用它，将绘制逻辑集中在图形层。

UIGQCanvas* canvas = new UIGQCanvas(parent);
canvas->setObjectName("annotationCanvas");
canvas->setThemeName("CanvasBg");
canvas->setDrawBackground(true);

常用接口：

接口	说明	参数	返回值
`setThemeName(const QString& themeName)`	设置画布主题。	`themeName`：主题名。	`void`
`setDrawBackground(bool draw)`	控制是否绘制背景。	`draw`：是否绘制。	`void`
`update()`	请求重新绘制。	无	`void`
`setMouseTracking(bool enable)`	设置鼠标追踪。	`enable`：是否追踪。	`void`
`paintEvent(QPaintEvent* event)`	Qt 绘制事件，业务可继承扩展。	`event`：绘制事件。	`void`
`mousePressEvent(QMouseEvent* event)`	鼠标按下事件。	`event`：鼠标事件。	`void`
`mouseMoveEvent(QMouseEvent* event)`	鼠标移动事件。	`event`：鼠标事件。	`void`
`mouseReleaseEvent(QMouseEvent* event)`	鼠标释放事件。	`event`：鼠标事件。	`void`

对于交互复杂的画布，建议拆分为数据层、绘制层和操作层，不要在 paintEvent 中直接计算大量业务数据。

UIGQOpenGLWidget 和 UIGQOGLWidget

UIGQOpenGLWidget / UIGQOGLWidget 用于需要硬件渲染的场景，例如 3D 模型、工业设备视图和高频图形刷新区域。

UIGQOGLWidget* view = new UIGQOGLWidget(parent);
view->setObjectName("sceneView");
view->setThemeName("OpenGLPanel");
view->setDrawBackground(false);

常用接口：

接口	说明	参数	返回值
`initializeGL()`	OpenGL 初始化回调。	无	`void`
`resizeGL(int width, int height)`	OpenGL 视口尺寸变化回调。	`width/height`：尺寸。	`void`
`paintGL()`	OpenGL 绘制回调。	无	`void`
`update()`	请求下一帧绘制。	无	`void`
`makeCurrent()`	使当前 OpenGL 上下文生效。	无	`void`
`doneCurrent()`	释放当前 OpenGL 上下文。	无	`void`
`setThemeName(const QString& themeName)`	设置外层主题。	`themeName`：主题名。	`void`
`setDrawBackground(bool draw)`	控制是否绘制背景。	`draw`：是否绘制。	`void`

使用建议

Chart 相关控件不要放在 WidgetKit 页面文档中，统一查看 ChartKit 文档。
高频绘制区域避免和复杂 QWidget 层级过度嵌套。
画布背景、边框和圆角仍建议通过 setThemeName(...) 绑定主题。
OpenGL 控件的生命周期要和页面切换协调，避免隐藏页面继续高频刷新。

Qt-UI WidgetKit 图形与画布控件

图形与画布控件

图形与画布控件

控件类型

类继承关系

UIGQCanvas

UIGQOpenGLWidget 和 UIGQOGLWidget

使用建议