Qt QDockWidget详解以及例程

引言

QDockWidget类提供了一个可以停靠在QMainWindow内的小窗口 (理论上可以在QMainWindow中任意排列)，也可以作为QMainWindow上的顶级窗口浮动 (类似一个独立的窗口，可以通过拖动操作将QDockWidget浮动到任何位置)，也可以选择限制DockWidget移动、浮动和关闭的能力，以及它们可以放置的区域。

一、基本用法

• 在QMainWindow中将QDockWidget绘制成均匀排列 (如上图所示)，源码如下：

    ui->setupUi(this);QWidget *w = takeCentralWidget();delete w;// 创建QWidget *wid_a = new QWidget(this);wid_a->setStyleSheet("border: 2px solid #000000;");QDockWidget* dock_a = new QDockWidget(this);dock_a->setFeatures(QDockWidget::AllDockWidgetFeatures);dock_a->setWindowTitle("a");dock_a->setWidget(wid_a);QWidget *wid_b = new QWidget(this);wid_b->setStyleSheet("border: 2px solid #000000;");QDockWidget* dock_b = new QDockWidget(this);dock_b->setFeatures(QDockWidget::AllDockWidgetFeatures);dock_b->setWindowTitle("b");dock_b->setWidget(wid_b);QWidget *wid_c = new QWidget(this);wid_c->setStyleSheet("border: 2px solid #000000;");QDockWidget* dock_c = new QDockWidget(this);dock_c->setFeatures(QDockWidget::AllDockWidgetFeatures);dock_c->setWindowTitle("c");dock_c->setWidget(wid_c);QWidget *wid_d = new QWidget(this);wid_d->setStyleSheet("border: 2px solid #000000;");QDockWidget* dock_d = new QDockWidget(this);dock_d->setFeatures(QDockWidget::AllDockWidgetFeatures);dock_d->setWindowTitle("d");dock_d->setWidget(wid_d);// 布局addDockWidget(Qt::DockWidgetArea::LeftDockWidgetArea, dock_a);splitDockWidget(dock_a, dock_b, Qt::Orientation::Horizontal);splitDockWidget(dock_a, dock_c, Qt::Orientation::Vertical);splitDockWidget(dock_b, dock_d, Qt::Orientation::Vertical);

其他示例可参考：

1. QDockWidget 用法示例代码QMainwindow：https://blog.csdn.net/lanmanck/article/details/122466337
2. Qt之QDockWidget窗口详解—含演示Demo：https://blog.csdn.net/ManagerUser/article/details/124892827
3. Qt QDockWidget嵌套布局详解-实现Visual Studio布局：https://www.cnblogs.com/ybqjymy/p/14577183.html

二、深入了解

只列举了相关常用函数，更多细节可参考官方文档。

2.1 窗口功能相关

• 1. void setFeatures(QDockWidget::DockWidgetFeatures features)

设置QDockWidget的功能，是否可移动、可关闭和可浮动 (默认可以)。可传入的参数如下表所示：

常量	值	描述
QDockWidget::DockWidgetClosable	0x01	可关闭
QDockWidget::DockWidgetMovable	0x02	可移动
QDockWidget::DockWidgetFloatable	0x04	可浮动
QDockWidget::DockWidgetVerticalTitleBar	0x08	左侧显示垂直标题
QDockWidget::AllDockWidgetFeatures	0x07	可关闭、移动和浮动 (不建议使用)
QDockWidget::NoDockWidgetFeatures	0x00	无法关闭、移动和浮动

• 2. QDockWidget::DockWidgetFeatures features() const可获取当前QDockWidget的DockWidgetFeatures ，并且当其DockWidgetFeatures 改变时，会发送featuresChanged信号，详见setFeatures函数部分源码：

void QDockWidget::setFeatures(QDockWidget::DockWidgetFeatures features)
{Q_D(QDockWidget);features &= DockWidgetFeatureMask;if (d->features == features)return;const bool closableChanged = (d->features ^ features) & DockWidgetClosable;d->features = features;QDockWidgetLayout *layout= qobject_cast<QDockWidgetLayout*>(this->layout());layout->setVerticalTitleBar(features & DockWidgetVerticalTitleBar);d->updateButtons();d->toggleViewAction->setEnabled((d->features & DockWidgetClosable) == DockWidgetClosable);emit featuresChanged(d->features);  // 发送信号... 以下省略

2.2 停靠区域限制

• 1. void setAllowedAreas(Qt::DockWidgetAreas areas)

设置可以放置QDockWidget的区域，默认为Qt::AllDockWidgetAreas.可传入的参数如下表所示：

常量	值	描述
Qt::LeftDockWidgetArea	0x1	可停靠左侧
Qt::RightDockWidgetArea	0x2	可停靠右侧
Qt::TopDockWidgetArea	0x4	可停靠上侧
Qt::BottomDockWidgetArea	0x8	可停靠下侧
Qt::AllDockWidgetAreas	DockWidgetArea_Mask (0xf)	哪都能停
Qt::NoDockWidgetArea	0	停靠不了一点

• 2. Qt::DockWidgetAreas allowedAreas() const可获取当前QDockWidget的DockWidgetAreas，并且当其DockWidgetAreas改变时，会发送allowedAreasChanged信号。

2.3 在主窗体布局

这个用的比较多

• 1. void QMainWindow::addDockWidget(Qt::DockWidgetArea area, QDockWidget *dockwidget)
     重载函数void QMainWindow::addDockWidget(Qt::DockWidgetArea area, QDockWidget *dockwidget, Qt::Orientation orientation)，可修改方向，垂直 or 水平。

将QDockWidget添加到指定区域 - 上下左右，其中参数是TopDockWidgetArea默认水平排列 (如下图所示)，如果是LeftDockWidgetArea默认垂直排列。

addDockWidget(Qt::DockWidgetArea::TopDockWidgetArea, dock_a);
addDockWidget(Qt::DockWidgetArea::TopDockWidgetArea, dock_b);
addDockWidget(Qt::DockWidgetArea::TopDockWidgetArea, dock_c);
addDockWidget(Qt::DockWidgetArea::TopDockWidgetArea, dock_d);

• 2. void QMainWindow::splitDockWidget(QDockWidget *first, QDockWidget *second, Qt::Orientation orientation)

将第一个QDockWidget 覆盖的空间分成两部分，分别放入两个QDockWidget (方向指定了QDockWidget的空间排列方式：设置为水平则第二个QDockWidget放置在第一个的右边；设置为垂直则将第二个dock小部件放在第一个下面)

• 3. void QMainWindow::tabifyDockWidget(QDockWidget *first, QDockWidget *second)

合并窗口：将第二个QDockWidget嵌套合并到到第一个QDockWidget的位置，位置下方有标签可以切换显示的窗口。

addDockWidget(Qt::DockWidgetArea::TopDockWidgetArea, dock_a);
tabifyDockWidget(dock_a, dock_b);
addDockWidget(Qt::DockWidgetArea::TopDockWidgetArea, dock_c);
addDockWidget(Qt::DockWidgetArea::TopDockWidgetArea, dock_d);

• 3. void QMainWindow::setCorner(Qt::Corner corner, Qt::DockWidgetArea area)

指定某个DockWidgetArea的QDockWidget设置为占据给定的角 (就四个角，不展开描述了)。示例如下：

不加setCorner，后来加的两个(Top)窗口就把a b俩(left)窗口挤下去了，如果设置左侧停靠区域的窗口占据左上角，那么a b就到左上角，c d往右排. (实际使用，特别是存在大量窗口时用的比较少)，具体布局代码如下所示：

addDockWidget(Qt::DockWidgetArea::LeftDockWidgetArea, dock_a);
addDockWidget(Qt::DockWidgetArea::LeftDockWidgetArea, dock_b);
addDockWidget(Qt::DockWidgetArea::TopDockWidgetArea, dock_c);
addDockWidget(Qt::DockWidgetArea::TopDockWidgetArea, dock_d);setCorner(Qt::TopLeftCorner, Qt::LeftDockWidgetArea);  // 加不加这行...

• 4. void setDockNestingEnabled(bool enabled)

如果是false，则停靠区域只能包含一行（水平或垂直）QDockWidget，限制较大。如果是True则可随意摆放，自由度更高，但是操作会略复杂，将QDockWidget移动到另一个QDockWidget上可能会嵌套合并或者垂直 or 水平排列，需要更细致的操作…