【Qt笔记】QToolBox控件详解

QToolBox是Qt框架中一个非常实用的容器控件，它提供了一种类似于标签页（Tab Widget）但布局更加紧凑的界面组织方式。QToolBox通过一系列的可点击选项卡来展示不同的内容或工具，每个选项卡可以关联一个QWidget实例，使得用户可以通过点击选项卡来切换显示不同的界面或功能。以下是对QToolBox控件的详细解析，包括其功能、属性设置、相关API、信号与槽机制，以及代码示例。

一、QToolBox的基本功能

1.1 分页布局

分页布局：QToolBox以标签页的形式展示多个页面，每个页面可以放置任何QWidget。

// 创建QToolBox  
QToolBox toolBox;  
  
// 创建并添加第一个页面  
QWidget *page1 = new QWidget();  
QLabel *label1 = new QLabel("这是第一个页面", page1);  
QVBoxLayout *layout1 = new QVBoxLayout(page1);  
layout1->addWidget(label1);  
toolBox.addItem(page1, "页面 1");  
  
// 创建并添加第二个页面  
QWidget *page2 = new QWidget();  
QLabel *label2 = new QLabel("这是第二个页面", page2);  
QVBoxLayout *layout2 = new QVBoxLayout(page2);  
layout2->addWidget(label2);  
toolBox.addItem(page2, "页面 2");  
  
// 设置窗口和布局  
toolBox.setWindowTitle("QToolBox 分页布局示例");  
toolBox.show();

1.2 可点击标签

可点击标签：顶部的标签可以点击，用来切换显示不同的页面内容。

顶部的标签是可点击的，用来切换显示不同的页面内容。上面的示例已经展示了这一点，因为当你点击任何一个标签时，相应的页面就会显示出来。

1.3 图标支持

图标支持：每个页面可以设置图标和文本，增强视觉提示。

// 创建QToolBox  
QToolBox toolBox;  
  
// 创建并添加第一个页面，包含图标  
QWidget *page1 = new QWidget();  
QLabel *label1 = new QLabel("带有图标的页面 1", page1);  
QVBoxLayout *layout1 = new QVBoxLayout(page1);  
layout1->addWidget(label1);  
QIcon icon1(":/path/to/icon1.png"); // 确保图标路径正确  
toolBox.addItem(page1, icon1, "页面 1");  
  
// 创建并添加第二个页面  
QWidget *page2 = new QWidget();  
QLabel *label2 = new QLabel("页面 2", page2);  
QVBoxLayout *layout2 = new QVBoxLayout(page2);  
layout2->addWidget(label2);  
toolBox.addItem(page2, "页面 2");  
  
// 设置窗口和布局  
toolBox.setWindowTitle("QToolBox 图标支持示例");  
toolBox.show();

注意：:/path/to/icon1.png是资源文件的路径，你需要将图标添加到Qt资源文件中，并使用相应的路径。

1.4 信号与槽

信号与槽：提供了页面改变的信号，便于响应用户操作。

#include <QApplication>  
#include <QToolBox>  
#include <QLabel>  
#include <QVBoxLayout>  
#include <QDebug>  
  
class MyToolBox : public QToolBox {  
    Q_OBJECT  
public:  
    MyToolBox(QWidget *parent = nullptr) : QToolBox(parent) {  
        // 初始化代码（如果有的话）  
        connect(this, &QToolBox::currentChanged, this, &MyToolBox::onCurrentChanged);  
    }  
  
private slots:  
    void onCurrentChanged(int index) {  
        qDebug() << "当前页面索引已改变：" << index;  
    }  
};  
  
int main(int argc, char *argv[]) {  
    QApplication app(argc, argv);  
  
    // 使用自定义的MyToolBox  
    MyToolBox toolBox;  
  
    // 添加页面...（同上）  
  
    // 设置窗口和布局  
    toolBox.setWindowTitle("QToolBox 信号与槽示例");  
    toolBox.show();  
  
    return app.exec();  
}

二、 QToolBox的属性设置

2.1 设置指定索引位置可用性

setItemEnabled：设置指定索引位置的选项卡是否可用。

void QToolBox::setItemEnabled(int index, bool enabled);

index：选项卡索引。

enabled：启用或禁用标志。

2.2 设置指定索引位置图标

setItemIcon：设置指定索引位置的选项卡的图标。

void QToolBox::setItemIcon(int index, const QIcon &icon);

index：选项卡索引。

icon：要设置的图标。

2.3 设置标题

setItemText：设置指定索引位置的选项卡的标题。

void QToolBox::setItemText(int index, const QString &text);

index：选项卡索引。

text：要设置的标题文本。

2.4 设置提示信息

setItemToolTip：设置指定索引位置的选项卡的提示信息。

void QToolBox::setItemToolTip(int index, const QString &toolTip);

index：选项卡索引。

toolTip：要设置的提示信息。

2.5 获取信息

itemIcon、itemText、itemToolTip：分别用于获取指定索引位置的选项卡的图标、标题和提示信息。

三、QToolBox的常用API

3.1 构造函数

QToolBox::QToolBox(QWidget *parent = Q_NULLPTR, Qt::WindowFlags f = Qt::WindowFlags());

parent：父窗口指针，可选。

f：窗口标志，可选。

3.2 添加页面

3.2.1 尾部添加

addItem：在工具箱尾部添加一个选项卡（页面）。

int QToolBox::addItem(QWidget *widget, const QString &text);  
int QToolBox::addItem(QWidget *widget, const QIcon &icon, const QString &text);

widget：添加到工具箱中的子窗口对象。

icon：工具箱新的选项卡上显示的图标，可选。

text：工具箱新的选项卡上显示的标题。

3.2.2 指定位置添加

insertItem：在工具箱的指定位置插入一个选项卡（页面）。

int QToolBox::insertItem(int index, QWidget *widget, const QString &text);  
int QToolBox::insertItem(int index, QWidget *widget, const QIcon &icon, const QString &text);

index：指定在工具箱中插入的新选项卡的位置。

3.3 移除页面

removeItem：从工具箱中移除指定位置的选项卡（页面）。

void QToolBox::removeItem(int index);

index：要移除的选项卡索引。

四、应用示例

QToolBox控件在 Qt 中是一个相当灵活的组件，用于以标签页的形式组织多个界面元素。虽然其基本用法相对简单，但通过一些高级应用，你可以使 QToolBox更加丰富和动态。以下是一个 QToolBox控件的高级应用示例，包括动态添加和删除页面、使用自定义小部件以及处理页面变化时的逻辑。

4.1 代码

#include <QApplication>  
#include <QToolBox>  
#include <QWidget>  
#include <QVBoxLayout>  
#include <QPushButton>  
#include <QLabel>  
#include <QHBoxLayout>  
#include <QLineEdit>  
#include <QMessageBox>  
  
class DynamicToolBox : public QToolBox {  
    Q_OBJECT  
  
public:  
    DynamicToolBox(QWidget *parent = nullptr) : QToolBox(parent) {  
        // 初始化UI  
        setupUi();  
        // 连接信号  
        connect(addButton, &QPushButton::clicked, this, &DynamicToolBox::addPage);  
        connect(removeButton, &QPushButton::clicked, this, &DynamicToolBox::removeCurrentPage);  
    }  
  
private slots:  
    void addPage() {  
        // 创建一个新的页面  
        QWidget *page = new QWidget();  
        QLabel *label = new QLabel(tr("新页面 %1").arg(count() + 1), page);  
        QLineEdit *lineEdit = new QLineEdit(page);  
        QHBoxLayout *layout = new QHBoxLayout(page);  
        layout->addWidget(label);  
        layout->addWidget(lineEdit);  
  
        // 添加页面到QToolBox，并设置标题  
        addItem(page, tr("页面 %1").arg(count() + 1));  
  
        // 可选：存储对页面的引用，以便后续操作  
        // 例如：将 page 指针存储到某个容器中  
    }  
  
    void removeCurrentPage() {  
        // 检查是否有页面可以移除  
        if (count() > 0) {  
            // 移除当前选中的页面  
            removeItem(currentIndex());  
        } else {  
            QMessageBox::warning(this, tr("警告"), tr("没有页面可以移除！"));  
        }  
    }  
  
private:  
    QPushButton *addButton;  
    QPushButton *removeButton;  
  
    void setupUi() {  
        // 创建一个布局用于放置按钮  
        QVBoxLayout *layout = new QVBoxLayout(this);  
  
        // 添加“添加页面”按钮  
        addButton = new QPushButton(tr("添加页面"), this);  
        layout->addWidget(addButton);  
  
        // 添加“移除页面”按钮  
        removeButton = new QPushButton(tr("移除页面"), this);  
        layout->addWidget(removeButton);  
  
        // 注意：我们不需要在这里添加QToolBox的页面，因为它们将通过按钮操作动态添加  
    }  
};  
  
int main(int argc, char *argv[]) {  
    QApplication app(argc, argv);  
  
    DynamicToolBox toolBox;  
    toolBox.setWindowTitle(tr("QToolBox 高级应用示例"));  
    toolBox.show();  
  
    return app.exec();  
}

4.2 实现效果

4.3 解析

类定义：DynamicToolBox 类继承自 QToolBox，并添加了两个私有槽 addPage 和 removeCurrentPage 用于处理页面添加和删除。

UI 设置：在 setupUi 方法中，我们为 DynamicToolBox 添加了两个按钮（添加和删除），并将它们放置在一个垂直布局中。注意，我们没有在这里添加任何页面到 QToolBox，因为页面将通过按钮操作动态生成。

添加页面：当用户点击“添加页面”按钮时，addPage 槽函数被调用。该函数创建一个新的 QWidget，为其添加一些子控件（如 QLabel 和 QLineEdit），并使用 addItem 方法将其作为新页面添加到 QToolBox 中。页面标题是动态生成的，基于当前的页面数量。

移除页面：当用户点击“移除页面”按钮时，removeCurrentPage 槽函数被调用。该函数首先检查是否有页面可以移除（即 count() > 0），然后使用 removeItem 方法移除当前选中的页面。

信号与槽：通过 connect 函数，我们将按钮的 clicked 信号连接到相应的槽函数上，以便在用户交互时执行相应的操作。

注意：在上面的代码中，我们没有存储对动态创建页面的引用。如果你需要在后续操作中访问这些页面（例如，更新页面内容或检索用户输入），你可能需要将页面指针存储到某个容器（如 QList<QWidget*>）中。然而，在这个简单的示例中，我们专注于展示如何动态地添加和移除页面。

结语

QToolBox是Qt中一个非常实用的容器控件，它通过分页布局和可点击的标签提供了一种高效、用户友好的界面组织方式。通过本文的详细解析和代码示例，希望能帮助读者更好地理解和运用QToolBox控件，在Qt项目中创建出更加高效和用户友好的界面布局。