菜单

高级控件

相关源文件

本页面介绍了 Dear ImGui 中除基本按钮、复选框和文本输入框之外的更复杂的小部件组件。高级小部件提供更丰富的交互模式、复杂的数据可视化和专用输入方法。这些组件通常结合了多个基本小部件,或实现了更复杂的交互状态和行为。

有关按钮、复选框和基本文本输入框等基本小部件的信息,请参阅 基本小部件。有关表格的特定文档,请参阅 表格系统。有关详细的文本输入和编辑功能,请参阅 文本输入与编辑

小部件类型概览

Dear ImGui 提供了多种高级小部件,可按以下类别划分:

来源:imgui_widgets.cpp395-413 imgui_demo.cpp76-100

拖动控件和滑块

拖动控件和滑块提供了一种在指定范围内调整数值的交互方式。它们支持各种数据类型(浮点数、整数等),并可以配置不同的标志来定制行为。

主要功能

  • 拖动控件:通过单击和拖动来更改数值
  • 滑块:具有可供用户滑动的滑块的视觉表示
  • 范围限制:强制执行最小值和最大值边界
  • 格式自定义:使用自定义格式显示数值
  • 幂/对数刻度:非线性数值分布

来源:imgui_widgets.cpp3400-4250

使用示例

拖动控件具有格式、速度控制和幂曲线选项

来源:imgui_demo.cpp2000-2100

内部实现

拖动控件和滑块共享通用架构

  1. 标量版本(DragScalarSliderScalar)提供核心功能
  2. 特定于类型的版本是调用标量版本的便捷包装器
  3. 两者都使用 ButtonBehavior 进行交互检测
  4. 值更改通过 DragBehaviorSliderBehavior 实现

对于滑块,视觉外观是表示范围内值的填充矩形,而拖动控件默认仅显示文本。

来源:imgui_widgets.cpp3400-4250

颜色编辑器和拾色器

Dear ImGui 提供了全面的颜色处理小部件,支持 RGB 和 HSV 色彩空间,并带有可选的 Alpha 通道。

颜色小部件类型

来源:imgui_widgets.cpp4550-5400

主要功能

  • RGB/HSV 模式:在不同的色彩空间中编辑颜色
  • Alpha 支持:可选的透明度编辑
  • 十六进制输入:直接输入十六进制颜色值
  • 复制/粘贴:内置颜色值的剪贴板支持
  • 预览选项:带有透明度的颜色预览的不同方式
  • 下拉式拾色器:嵌入式颜色轮和渐变编辑器

颜色小部件使用浮点数值数组(RGB/RGBA 为 3 或 4 个分量)进行工作。数值范围为 0.0f 到 1.0f。

来源:imgui_widgets.cpp4550-5400

树节点和折叠标题

树节点提供 UI 元素的层次化组织,支持可折叠部分、选择和各种显示样式。

树形小部件变体

来源:imgui_widgets.cpp5600-5850

主要功能

  • 层次化显示:创建可折叠的层次结构以组织内容
  • 状态持久性:折叠/展开状态可以保存在 .ini 设置中
  • 选择:带有回调的视觉选择状态以进行交互
  • 样式选项:框架、叶节点和其他视觉自定义
  • 上下文感知:与项目悬停和焦点系统集成

树节点需要匹配的函数调用对

来源:imgui_demo.cpp4200-4400

拖放系统

拖放系统允许在小部件之间传输数据,并在操作过程中提供视觉反馈。

来源:imgui_widgets.cpp6000-6300

核心概念

  1. :启动拖动操作的小部件
  2. 载荷:正在传输的数据(类型由字符串标识)
  3. 目标:可以接收拖动数据的小部件
  4. 反馈:拖动操作期间的视觉指示器

拖放系统是有状态的,具有源和目标双方操作的独特开始/结束函数对。载荷数据被复制以确保正确帧之间的传输。

来源:imgui_internal.h80-90

绘图小部件

Dear ImGui 包括基本的绘图功能,可用于在不依赖外部库的情况下可视化数据。

绘图类型

来源:imgui_widgets.cpp7100-7300

用途

这些绘图小部件接受数值数组或函数回调

这些小部件针对数据的快速显示进行了优化,而不是交互式操作。它们支持刻度、叠加和尺寸的基本自定义。

来源:imgui_demo.cpp2800-3000

多选

多选功能允许用户从列表中选择多个项目,支持键盘导航、Shift 选择和其他常见的选择模式。

来源:imgui_widgets.cpp6500-6900

主要功能

  • 范围选择:使用 Shift 键选择多个项目
  • 切换选择:使用 Ctrl 键添加/移除项目
  • 键盘导航:箭头键和其他导航控件
  • 选择反馈:选定项目的视觉指示器
  • 可自定义存储:内置或自定义选择存储

此系统与其他小部件(如 Selectable()、列表框和树节点)集成,在不同类型的小部件中提供一致的多选行为。

来源:imgui_internal.h188-193

选项卡系统

标签页提供了一种将内容组织成可切换页面的方法。

来源:imgui_widgets.cpp8400-8900

主要功能

  • 内容组织:将相关内容分组到标签页中
  • 可重排标签:用户可以通过拖动标签来重新排序
  • 关闭按钮:可选的关闭标签按钮
  • 溢出处理:标签过多时的滚动或下拉菜单
  • 样式选项:各种视觉自定义选项
  • 程序化控制:用于标签选择和状态查询的 API

标签页系统使用与树相似的模式,即仅在标签激活时才渲染标签内容。

来源:imgui_demo.cpp3600-3800

小部件生命周期和内部架构

了解小部件的内部架构对于创建自定义小部件或调试问题很有帮助。

来源:imgui_internal.h170-180 imgui_widgets.cpp130-150

小部件交互架构

下图展示了小部件如何与输入、状态跟踪和渲染系统进行交互。

来源:imgui_internal.h180-200 imgui.cpp8600-8700

高级小部件技术

小部件内的自定义渲染

您可以将标准小部件行为与自定义渲染相结合。

访问小部件状态

Dear ImGui 提供函数来查询最后一个项目的状态。

  • IsItemHovered():检查鼠标是否悬停在最后一个项目上
  • IsItemActive():检查最后一个项目当前是否处于活动状态(正在交互)
  • IsItemFocused():检查最后一个项目是否具有键盘焦点
  • IsItemClicked():检查最后一个项目是否被点击
  • IsItemEdited():检查最后一个项目是否被编辑(值已更改)
  • GetItemRectMin()/Max():获取最后一个项目的边界

这些函数对于创建复合小部件或添加自定义行为非常有用。

来源: imgui_internal.h200-220 imgui.h400-450

组合多个控件

通过组合多个基本控件并管理它们的状,可以创建复杂的控件。

来源: imgui_demo.cpp2200-2300

结论

Dear ImGui 中的高级控件提供了比基本 UI 元素更丰富的交互模式和专门的功能。通过了解它们的用户界面应用程序接口、行为和内部结构,您可以有效地使用这些组件,甚至创建自定义控件来构建复杂的界面。

如需与大型系统集成,请参阅 表格系统集成指南 页面。