一.基本概念

QDockWidget是Qt框架中的一个窗口部件，它实现了可停靠的窗口功能。在QMainWindow中，QDockWidget可以作为辅助窗口停靠在主窗口的四周（左侧、右侧、顶部或底部），也可以作为独立的浮动窗口出现在主窗口之外。

QDockWidget提供了灵活的布局管理和标题栏定制，允许用户根据需要调整窗口的位置和大小，以及显示或隐藏窗口。

注意：

     只有QMainWindow类才有addDockWidget方法,也就是说DockWidget只能放到QMainWindow里面使用。

二.功能特性

1.停靠功能：

QDockWidget允许用户将窗口部件停靠在主窗口的各个位置，如左侧、右侧、上方或下方。

用户可以通过拖动和放置的方式改变QDockWidget的停靠位置，将其移动到新的区域。

2.浮动窗口：

QDockWidget具备浮动功能，用户可以将其拖动到主窗口之外，使其成为一个独立的浮动窗口。

浮动窗口可以调整位置和大小，并可以重新停靠在主窗口的任意位置。

3.可关闭：

QDockWidget可以关闭，允许用户根据需要隐藏或显示它。

关闭QDockWidget后，它不会从内存中删除，只是从界面上隐藏起来，用户可以通过调用相关方法将其重新显示。

4.自定义部件：

用户可以将自定义的部件放在QDockWidget中，以构建自定义的界面元素。

通过设置QWidget对象作为QDockWidget的子部件，可以显示各种内容，如表单、文本编辑器、按钮等。

5.标题栏定制：

QDockWidget提供了标题栏定制功能，用户可以通过设置自定义的标题栏控件来替换默认的标题栏。

自定义标题栏控件可以包含各种控件元素，如按钮、文本框等，以实现更丰富的界面交互。

三.常用方法

QDockWidget类提供了一系列函数，用于配置和管理停靠式窗口的行为和外观。以下是一些常用的QDockWidget方法的介绍和使用方法：

1.设置和获取部件

setWidget(QWidget *widget)：将一个 QWidget 设置为 QDockWidget 的内容部件。例如，如果有一个自定义的 QWidget 派生类 MyWidget，可以这样设置：

MyWidget *myWidget = new MyWidget;

dockWidget->setWidget(myWidget);

2.设置停靠区域

setAllowedAreas(Qt::DockWidgetAreas areas)：指定QDockWidget可以停靠的区域。

Qt::DockWidgetAreas是一个枚举类型，包括 Qt::LeftDockWidgetArea（左侧）、Qt::RightDockWidgetArea（右侧）、Qt::TopDockWidgetArea（顶部）、Qt::BottomDockWidgetArea（底部）以及它们的组合。

例如，允许在左侧和顶部停靠：

dockWidget->setAllowedAreas(Qt::LeftDockWidgetArea | Qt::TopDockWidgetArea);

3.设置标题栏文本

setWindowTitle(const QString &title)：可以动态地改变QDockWidget标题栏的文本。

dockWidget->setWindowTitle("这是新标题");

4.设置功能特性

void setFeatures(QDockWidget::DockWidgetFeatures features)：设置QDockWidget的功能特性，如关闭按钮、可移动、可浮动等。

QDockWidget::DockWidgetFeatures 枚举中一些常用特性标志的详细介绍：

QDockWidget::DockWidgetClosable：如果设置了此标志，QDockWidget 将显示一个关闭按钮，用户可以通过点击它来关闭（隐藏）QDockWidget 。

QDockWidget::DockWidgetMovable：如果设置了此标志，QDockWidget 可以在其允许的停靠区域内被拖动和重新定位。

QDockWidget::DockWidgetFloatable：如果设置了此标志，QDockWidget 可以被拖出停靠区域并浮动为一个独立的窗口。

QDockWidget::DockWidgetVerticalTitleBar：（在Qt 6中已弃用）：如果设置了此标志（注意，这个标志在Qt 6中已经被移除，因为Qt 6中的 QDockWidget 默认总是使用垂直标题栏），QDockWidget 的标题栏将垂直显示（通常这是不必要的，因为默认行为就是垂直的）。

QDockWidget::AllDockWidgetFeatures：这是一个方便的标志，它包含了上述所有特性标志（除了已弃用的 DockWidgetVerticalTitleBar）。

// 创建一个QDockWidget

QDockWidget *dockWidget = new QDockWidget("Dockable with Features", &mainWindow);

// 设置QDockWidget的功能特性：可关闭、可移动、可浮动

dockWidget->setFeatures(QDockWidget::DockWidgetClosable | QDockWidget::DockWidgetMovable | QDockWidget::DockWidgetFloatable);

5.显示或隐藏窗口

void setVisible(bool visible)：显示或隐藏QDockWidget。如果设置为true，则显示窗口；如果设置为false，则隐藏窗口。

bool isVisible() const：返回窗口是否可见。如果窗口可见，则返回true；否则返回false。

例：下方代码设置窗口是否可见，如果当前窗口是可见的，则将其设置为不可见；如果当前窗口是不可见的，则将其设置为可见。

dockWidget->setVisible(!dockWidget->isVisible());

6.设置或获取自定义标题栏

void setTitleBarWidget(QWidget *widget)：设置自定义的标题栏控件，替换掉默认的标题栏。

QWidget *titleBarWidget()：返回自定义的标题栏控件。

7.应用场景

QDockWidget控件的应用场景比较像vs软件中的各种工具栏的功能，可以移动、关闭及悬浮，如下图红框内部分所示：

四.应用示例代码

1.mainwindow.h

#ifndef MAINWINDOW_H

#define MAINWINDOW_H

#include <QMainWindow>

#include <QTextEdit>

#include <QDockWidget>

#include <QColorDialog>

#include <QPushButton>

#include <QVBoxLayout>

QT_BEGIN_NAMESPACE

namespace Ui {

class MainWindow;

}

QT_END_NAMESPACE

class MainWindow : public QMainWindow

{

    Q_OBJECT

public:

    MainWindow(QWidget *parent = nullptr);

    ~MainWindow();

private slots:

    void changeBackgroundColor();

private:

    QTextEdit *textEdit;

    QDockWidget *dockWidget;

private:

    Ui::MainWindow *ui;

};

#endif // MAINWINDOW_H

2.mainwindow.cpp

#include "mainwindow.h"

#include "ui_mainwindow.h"

MainWindow::MainWindow(QWidget *parent)

    : QMainWindow(parent)

    , ui(new Ui::MainWindow)

{

    ui->setupUi(this);

    // 创建文本编辑部件

    textEdit = new QTextEdit(this);

    setCentralWidget(textEdit);

    // 创建QDockWidget

    dockWidget = new QDockWidget(tr("Color Chooser"), this);

    // 设置可移动、可浮动、可关闭功能

    dockWidget->setFeatures(QDockWidget::DockWidgetClosable | QDockWidget::DockWidgetFloatable | QDockWidget::DockWidgetMovable);

    // 创建一个按钮用于触发颜色选择对话框

    QPushButton *button = new QPushButton(tr("Change Background Color"), this);

    connect(button, &QPushButton::clicked, this, &MainWindow::changeBackgroundColor);

    // 将按钮添加到QDockWidget的布局中

    QVBoxLayout *layout = new QVBoxLayout;

    layout->addWidget(button);

    QWidget *widget = new QWidget;

    widget->setLayout(layout);

    dockWidget->setWidget(widget);

    // 将QDockWidget添加到主窗口

    addDockWidget(Qt::RightDockWidgetArea, dockWidget);

}

MainWindow::~MainWindow()

{

    delete ui;

}

void MainWindow::changeBackgroundColor()

{

    QColor color = QColorDialog::getColor(Qt::white, this);

    if (color.isValid()) {

        textEdit->setStyleSheet(QString("QTextEdit { background-color: %1 }").arg(color.name()));

    }

}

3.效果图