当前位置：首页 > news >正文

Qt QToolBox 组件总结

news 来源：原创 2025/5/14 20:45:54

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) 插入页面。