Qt QToolBox 组件总结

Qt QToolBox 组件总结

1. 概述

• 用途：QToolBox 是一个垂直堆叠的可折叠面板容器，每个面板通过标签切换显示。适用于需要节省空间的界面设计（如工具选项板、设置窗口）。
• 特点：一次仅显示一个面板，点击标签展开内容，其他面板自动折叠。继承自 QFrame，支持样式自定义。

2. 创建与基本用法

• 头文件：#include <QToolBox>
• 添加页面：

  QToolBox *toolBox = new QToolBox;
  QWidget *page1 = new QWidget;
  QWidget *page2 = new QWidget;
  // 添加页面（参数：内容控件、图标、标签文本）
  toolBox->addItem(page1, QIcon(), "Page 1");
  toolBox->addItem(page2, "Page 2"); // 无图标版本
  

3. 常用方法与属性

• 页面管理：
  • int currentIndex()：获取当前页面索引。
  • void setCurrentIndex(int index)：切换页面。
  • int count()：返回页面总数。
• 标签与图标：
  • QString itemText(int index) / void setItemText(int index, const QString &text)：获取/设置标签文本。
  • QIcon itemIcon(int index) / void setItemIcon(int index, const QIcon &icon)：获取/设置标签图标。
• 页面控件：
  • QWidget *widget(int index)：获取指定页面的控件。

4. 信号与槽

• 关键信号：
  • currentChanged(int index)：当前页面切换时触发。
• 示例连接：

  connect(toolBox, &QToolBox::currentChanged, [](int index) {
      qDebug() << "当前页面索引：" << index;
  });
  

5. 样式与外观

• QSS 示例：

  QToolBox::tab {
      background: #f0f0f0;
      border: 1px solid #ccc;
      padding: 5px;
  }
  QToolBox::tab:selected { /* 选中标签样式 */ }
  

6. 注意事项

• 布局管理：每个页面内的控件需合理布局（使用 QVBoxLayout 等），避免内容显示异常。
• 动态更新：修改页面内容时，通过 widget(index) 获取控件后调整。
• 索引安全：动态增删页面时，确保索引有效（避免越界）。

7. 与 QTabWidget 的区别

• 布局方向：QToolBox 垂直排列标签，适合紧凑空间；QTabWidget 水平/垂直标签栏，适合多页平铺。
• 交互方式：QToolBox 标签带折叠箭头，展开内容在下方；QTabWidget 直接切换标签对应内容区域。

8. 完整示例代码

#include <QApplication>
#include <QToolBox>
#include <QVBoxLayout>
#include <QPushButton>
#include <QLabel>

int main(int argc, char *argv[]) {
    QApplication a(argc, argv);
    QWidget window;
    QVBoxLayout *layout = new QVBoxLayout(&window);

    QToolBox *toolBox = new QToolBox;
    // 创建页面1
    QWidget *page1 = new QWidget;
    QPushButton *button = new QPushButton("按钮", page1);
    QVBoxLayout *page1Layout = new QVBoxLayout(page1);
    page1Layout->addWidget(button);
    // 创建页面2
    QWidget *page2 = new QWidget;
    QLabel *label = new QLabel("这是一个标签", page2);
    QVBoxLayout *page2Layout = new QVBoxLayout(page2);
    page2Layout->addWidget(label);
    
    toolBox->addItem(page1, "工具");
    toolBox->addItem(page2, QIcon(), "信息");
    layout->addWidget(toolBox);
    
    window.show();
    return a.exec();
}

9. 扩展功能

• 禁用页面：通过 setItemEnabled(int index, bool enabled) 控制标签是否可点击。
• 动态增删：使用 removeItem(int index) 移除页面，或 insertItem(int index, QWidget *w, const QString &text) 插入页面。