qt-C++笔记之QSplitter

qt-C++笔记之QSplitter

code review!

在 Qt C++ 中，QSplitter 是一个用于创建可调整大小的分割窗口的控件，允许用户通过拖动分割条（splitter handle）动态调整子控件的大小。QSplitter 常用于创建灵活的布局，比如将界面分割成多个可调整大小的区域，类似于文件管理器或 IDE 中的面板布局。

1. QSplitter 概述

基本信息

• 头文件：#include <QSplitter>
• 继承自：QFrame（因此也间接继承自 QWidget）
• 功能：
  • 将窗口分割成多个子区域，每个区域可以包含一个 QWidget（如 QTextEdit、QTreeView 等）
  • 用户可以通过拖动分割条调整子控件的大小
  • 支持水平（Horizontal）或垂直（Vertical）分割

2. 主要特性

2.1 分割方向

通过 setOrientation() 设置分割方向：

• Qt::Horizontal：水平分割（子控件左右排列）
• Qt::Vertical：垂直分割（子控件上下排列）

2.2 子控件管理

• 使用 addWidget() 或 insertWidget() 添加子控件
• 子控件会按照添加顺序排列

2.3 大小策略

• 通过 setSizes() 设置子控件的初始大小
• 通过 setStretchFactor() 设置子控件的拉伸因子，控制调整大小时的比例

2.4 分割条行为

• setHandleWidth() 设置分割条的宽度
• setCollapsible() 控制某个子控件是否可以被完全折叠（最小化到 0）

2.5 信号

• splitterMoved(int pos, int index)：当分割条被移动时发出，pos 是新位置，index 是分割条的索引

3. 常用方法

方法	描述
QSplitter(Qt::Orientation orientation, QWidget *parent = nullptr)	构造函数，指定分割方向和父控件
addWidget(QWidget *widget)	添加一个子控件到分割器
insertWidget(int index, QWidget *widget)	在指定索引处插入子控件
setOrientation(Qt::Orientation orientation)	设置分割方向（水平或垂直）
setSizes(const QList<int> &list)	设置每个子控件的初始大小
setStretchFactor(int index, int stretch)	设置指定索引子控件的拉伸因子
setCollapsible(int index, bool collapsible)	设置指定索引的子控件是否可折叠
setHandleWidth(int width)	设置分割条的宽度
sizes()	返回当前子控件的大小列表

4. 基础示例

以下是一个简单的示例，展示如何使用 QSplitter 创建一个包含两个子控件的水平分割窗口：

#include <QApplication>
#include <QSplitter>
#include <QTextEdit>
#include <QMainWindow>

int main(int argc, char *argv[]) {
    QApplication app(argc, argv);

    // 创建主窗口
    QMainWindow window;

    // 创建 QSplitter，水平方向
    QSplitter *splitter = new QSplitter(Qt::Horizontal);

    // 创建两个子控件
    QTextEdit *textEdit1 = new QTextEdit;
    textEdit1->setText("左侧文本编辑器");
    QTextEdit *textEdit2 = new QTextEdit;
    textEdit2->setText("右侧文本编辑器");

    // 将子控件添加到 QSplitter
    splitter->addWidget(textEdit1);
    splitter->addWidget(textEdit2);

    // 设置初始大小（可选）
    splitter->setSizes(QList<int>{200, 400});

    // 设置第一个子控件不可折叠
    splitter->setCollapsible(0, false);

    // 设置分割条宽度
    splitter->setHandleWidth(10);

    // 将 QSplitter 设置为主窗口的中央控件
    window.setCentralWidget(splitter);

    // 显示窗口
    window.resize(600, 400);
    window.show();

    return app.exec();
}

代码说明

• 创建一个水平方向的 QSplitter
• 添加两个 QTextEdit 作为子控件，分别显示在左右两侧
• 使用 setSizes() 设置初始宽度（左侧 200 像素，右侧 400 像素）
• 使用 setCollapsible(0, false) 禁止第一个子控件被完全折叠
• 将 QSplitter 设置为主窗口的中央控件

运行后，用户可以通过拖动分割条调整两个 QTextEdit 的大小。

运行效果

交互说明：

• 鼠标悬停在分割条上时，光标会变成左右调整大小的样式（↔）
• 按住鼠标左键并拖动分割条，可以实时调整两侧控件的大小
• 由于设置了 setCollapsible(0, false)，左侧控件不能被完全折叠

5. 高级用法

5.1 嵌套 QSplitter

QSplitter 可以嵌套使用，以创建复杂的布局。例如，创建一个垂直分割器，内部包含一个水平分割器：

#include <QApplication>
#include <QSplitter>
#include <QTextEdit>
#include <QMainWindow>

int main(int argc, char *argv[]) {
    QApplication app(argc, argv);
    QMainWindow window;

    // 外层垂直分割器
    QSplitter *verticalSplitter = new QSplitter(Qt::Vertical);

    // 内层水平分割器
    QSplitter *horizontalSplitter = new QSplitter(Qt::Horizontal);

    // 创建子控件
    QTextEdit *textEdit1 = new QTextEdit("左上");
    QTextEdit *textEdit2 = new QTextEdit("右上");
    QTextEdit *textEdit3 = new QTextEdit("底部");

    // 添加到水平分割器
    horizontalSplitter->addWidget(textEdit1);
    horizontalSplitter->addWidget(textEdit2);

    // 添加到垂直分割器
    verticalSplitter->addWidget(horizontalSplitter);
    verticalSplitter->addWidget(textEdit3);

    // 设置主窗口
    window.setCentralWidget(verticalSplitter);
    window.resize(600, 400);
    window.show();

    return app.exec();
}

效果：窗口被垂直分割为上下两部分，上部分又被水平分割为左右两部分。

模拟运行效果

布局特点：

• 垂直分割器将窗口分为上下两部分
• 上部分包含一个水平分割器，进一步分为左右两个区域
• 每个分割条都可以独立拖动，灵活调整各区域大小
• 这种嵌套结构可以创建复杂的多面板布局

5.2 保存和恢复布局

可以使用 saveState() 和 restoreState() 保存和恢复 QSplitter 的布局状态：

// 保存布局
QByteArray state = splitter->saveState();

// 恢复布局
splitter->restoreState(state);

这在需要持久化用户界面布局时非常有用（例如，保存到配置文件）。

6. 注意事项

6.1 子控件管理

• 添加到 QSplitter 的子控件由 QSplitter 管理，无需手动删除
• 可以通过 setMinimumSize() 或 setMaximumSize() 为子控件设置大小限制

6.2 事件处理

如果需要响应分割条的移动，可以连接 splitterMoved 信号

6.3 样式定制

分割条的外观可以通过 Qt 样式表（QSS）自定义，例如：

QSplitter::handle {
    background: gray;
    width: 10px;
}

7. 常见问题

Q：如何让某个子控件不可调整大小？

使用 setStretchFactor() 设置其他控件的拉伸因子为 0，或者通过 setFixedSize() 限制子控件大小。

Q：如何禁用分割条的拖动？

使用 setEnabled(false) 禁用整个 QSplitter，但这会禁用所有交互。更好的方法是为子控件设置固定大小。

Q：如何在运行时动态添加或移除子控件？

使用 addWidget() 或 insertWidget() 动态添加控件；通过 delete 或 removeWidget()（需要自定义）移除控件。

8. Linux 命令行编译

要在 Linux 环境下通过命令行编译上述使用 Qt C++ 和 QSplitter 的程序，需要确保已安装 Qt 开发环境，并使用 qmake 和 make 工具进行编译。以下是详细步骤，假设你的代码保存在 main.cpp 文件中。

8.1 创建项目文件

创建 splitter.pro 文件：

QT += core gui widgets
TARGET = splitter
TEMPLATE = app
SOURCES += main.cpp

8.2 编译步骤

# 生成 Makefile
qmake splitter.pro

# 编译程序
make

# 运行程序
./splitter