Qt-Advanced-Docking-System配置及使用、心得

Qt-Advanced-Docking-System

• 1. Qt-Advanced-Docking-System描述
• 2. 功能特点

• 2.1. 灵活的停靠方式
• 2.2. 嵌套停靠
• 2.3. 自定义布局保存与恢复
• 2.4. 外观和行为定制

• 3. 与Qt原生停靠系统的比较
• 4. 使用场景

• 4.1. 集成开发环境（IDE）
• 4.2. 图形设计软件
• 4.3. 数据分析和可视化工具

• 5. 下载链接
• 6. 构建
• 7. 创建`include`文件夹
• 8. 在`lib`和`include`同级目录创建`QtDock.pri`文件
• 9. 调用
• 10. 小栗子
• 11. 心得

1. Qt-Advanced-Docking-System描述

Qt - Advanced - Docking - System是一个用于Qt框架的扩展库，它提供了高级的停靠窗口（Docking Window）功能。在传统的图形用户界面（GUI）应用程序中，停靠窗口能够让用户灵活地组织和管理界面空间，方便用户根据自己的需求对各种工具窗口、信息窗口等进行布局。

2. 功能特点

2.1. 灵活的停靠方式

支持多种停靠方式，可以将窗口停靠在主窗口的边缘（上、下、左、右），就像许多集成开发环境（IDE）中的工具窗口一样。例如，在一个代码编辑器软件中，可以将文件浏览器窗口停靠在主编辑窗口的左侧，将调试信息窗口停靠在底部。而且，这些窗口还可以进行浮动（Floating）操作，用户能够将停靠窗口拖离主窗口的边缘，使其成为一个独立的浮动窗口，方便在多个屏幕或者复杂的布局场景下使用。

2.2. 嵌套停靠

允许嵌套停靠，这意味着可以在一个已停靠的窗口内部再创建停靠区域，实现更复杂的布局。例如，在一个图形处理软件中，可以在主图像显示窗口的一侧停靠一个包含多个工具选项卡（如颜色调整、滤镜等）的窗口，而在这个工具选项卡窗口内部，又可以将不同的工具组（如亮度/对比度调整组和色彩平衡调整组）进行进一步的停靠布局。

2.3. 自定义布局保存与恢复

能够帮助用户保存自定义的窗口布局，并且在下次启动应用程序时恢复。这对于那些有复杂工作流程和特定界面布局偏好的用户非常有用。比如，一个专业的音频编辑软件用户可能花费了很多时间来调整各个音频轨道窗口、效果窗口和混音窗口的布局，通过这个功能，下次打开软件时就可以快速恢复到之前的工作布局。

2.4. 外观和行为定制

提供了丰富的选项来定制停靠窗口的外观和行为。可以设置窗口的标题栏样式，包括按钮的显示（如最小化、最大化、关闭按钮）和外观。还可以控制窗口的拖动行为、缩放行为等。例如，在一个具有简洁风格要求的软件中，可以隐藏停靠窗口标题栏上的一些不必要的按钮，或者调整窗口拖动时的敏感度。

3. 与Qt原生停靠系统的比较

Qt本身自带了基本的停靠系统，但Qt - Advanced - Docking - System在功能上更加丰富和灵活。Qt原生停靠系统能够满足一些简单的应用场景，但在面对复杂的多窗口、嵌套式停靠以及高度定制化的需求时，可能会显得力不从心。
例如，Qt原生停靠系统在处理多个窗口之间的嵌套关系以及复杂的浮动和重新停靠操作时，可能没有Qt - Advanced - Docking - System那样直观和方便。

4. 使用场景

4.1. 集成开发环境（IDE）

在IDE中，通常需要同时展示多个工具窗口，如代码编辑器、项目资源管理器、调试控制台等。Qt - Advanced - Docking - System可以让这些窗口以灵活的方式停靠，方便开发者根据自己的编程习惯进行布局。而且，开发者可以方便地将某个窗口浮动出来，放在另一个屏幕上进行参考，比如将文档窗口浮动出来对照代码进行编写。

4.2. 图形设计软件

对于图形设计软件，需要各种工具窗口，如颜色调色板、图层管理、图形元素库等。通过该系统，可以将这些工具窗口以合适的方式停靠在主绘图窗口周围，并且可以根据用户的操作习惯进行布局调整，如将常用的工具窗口停靠在更方便操作的位置，或者将不常用的窗口隐藏或最小化。

4.3. 数据分析和可视化工具

在这类工具中，可能有数据输入窗口、数据处理窗口、图表显示窗口等多种窗口。使用Qt - Advanced - Docking - System可以实现这些窗口的有效布局，比如将数据输入和处理窗口停靠在一起，方便用户进行操作，同时将图表显示窗口以较大的空间进行停靠，便于观察数据可视化的结果。

5. 下载链接

链接: link https://github.com/githubuser0xFFFF/Qt-Advanced-Docking-System
下载后，得到一个压缩包，直接解压，使用QtCreator直接打开，使用库版本>5.8的得kit进行构建，因为里面用到的一个Q_NAMESPACE宏，是5.8版本开始引入的。我这里是使用Qt6版本，这个库也支持Qt6版本。

6. 构建

直接对src进行构建，构建完后，会生成lib文件夹，里面有.a 、 .dll 。

lib目录同级下的src目录是生成.o和makefile等文件的目录，可删除。

7. 创建include文件夹

在lib目录创建include文件夹，然后将Qt-Advanced-Docking-System-master目录下的src目录下的所有文件都拷贝到include文件夹，然后将所有.cpp文件删除，组成调用库的头文件目录。

8. 在lib和include同级目录创建QtDock.pri文件

接下来，创建个QtDock文件夹，将lib目录、include目录、QtDock.pri放到QtDock目录内。
在QtDock.pri文件添加内容如下，用于配置和调用，这样在.pro文件只需要引入QtDock.pri就可以使用了，酷：

LIBS += -L$$PWD/lib -lqtadvanceddocking

INCLUDEPATH += $$PWD/include/
DEPENDPATH += $$PWD/include/

QtDock.pri文件内容可根据系统、模式、编译器、或者一些其他配置进行自定义编写。
以上步骤6、步骤7、步骤8将QtDock配置成一个模块，便于引用。

9. 调用

创建新的Qt项目，将封装好的QtDock目录直接拷贝到Qt项目下。
在.pro文件中添加以下内容，就可以调用了：

include($$PWD/QtDock/QtDock.pri)

10. 小栗子

部分代码如下:

#include "mainwindow.h"
#include "ui_mainwindow.h"

#define VERSION 9527

int MainWindow::s_nIndex = 0;

MainWindow::MainWindow(QWidget *parent)
    : QMainWindow(parent)
    , ui(new Ui::MainWindow)
{
    ui->setupUi(this);

    m_pLabel = new QLabel();
    ui->statusbar->addWidget(m_pLabel);

    m_pMgr = new ads::CDockManager(this);
    setCentralWidget(m_pMgr);

    m_pWCentral = new ads::CDockWidget("中");
    m_pWLeft = new ads::CDockWidget("左");
    m_pWuP = new ads::CDockWidget("上");
    m_pWRight = new ads::CDockWidget("右");
    m_pWBottom = new ads::CDockWidget("下");

    m_pMgr->setCentralWidget(m_pWCentral);
    m_pWLeft->setWidget(new QLabel("左"));
    m_pWuP->setWidget(new QLabel("上"));
    m_pWRight->setWidget(new QLabel("右"));
    m_pWBottom->setWidget(new QLabel("下"));
    m_pWCentral->setWidget(new QLabel("中"));


    m_pMgr->addDockWidget(ads::DockWidgetArea::LeftDockWidgetArea, m_pWLeft);
    m_pMgr->addDockWidget(ads::DockWidgetArea::TopDockWidgetArea, m_pWuP);
    m_pMgr->addDockWidget(ads::DockWidgetArea::RightDockWidgetArea, m_pWRight);
    m_pMgr->addDockWidget(ads::DockWidgetArea::BottomDockWidgetArea, m_pWBottom);
}

MainWindow::~MainWindow()
{
    delete ui;
}

void MainWindow::on_action_saveState_triggered()
{
    m_ba = m_pMgr->saveState(VERSION);
    m_pLabel->setText("保存布局.");
}

void MainWindow::on_action_restoreState_triggered()
{
    bool bRestore = m_pMgr->restoreState(m_ba, VERSION);
    if (bRestore)
        m_pLabel->setText("加载布局成功.");
}

void MainWindow::on_action_addUpLayout_triggered()
{
    s_nIndex++;
    ads::CDockWidget* pW = new ads::CDockWidget(QString("新添加  上  布局_%1").arg(s_nIndex));
    pW->setWidget(new QLabel(QString("新添加  上  布局")));
    m_pMgr->addDockWidget(ads::DockWidgetArea::CenterDockWidgetArea, pW, m_pWuP->dockAreaWidget());
}

void MainWindow::on_action_addBottomLayout_triggered()
{
    s_nIndex++;
    ads::CDockWidget* pW = new ads::CDockWidget(QString("新添加  下  布局_%1").arg(s_nIndex));
    pW->setWidget(new QLabel(QString("新添加  下  布局")));
    m_pMgr->addDockWidget(ads::DockWidgetArea::CenterDockWidgetArea, pW, m_pWBottom->dockAreaWidget());
}

void MainWindow::on_action_addLeftLayout_triggered()
{
    s_nIndex++;
    ads::CDockWidget* pW = new ads::CDockWidget(QString("新添加  左  布局_%1").arg(s_nIndex));
    pW->setWidget(new QLabel(QString("新添加  左  布局")));
    m_pMgr->addDockWidget(ads::DockWidgetArea::CenterDockWidgetArea, pW, m_pWLeft->dockAreaWidget());
}

void MainWindow::on_action_addRightLayout_triggered()
{
    s_nIndex++;
    ads::CDockWidget* pW = new ads::CDockWidget(QString("新添加  右  布局_%1").arg(s_nIndex));
    pW->setWidget(new QLabel(QString("新添加  右  布局")));
    m_pMgr->addDockWidget(ads::DockWidgetArea::CenterDockWidgetArea, pW, m_pWRight->dockAreaWidget());
}

11. 心得

1. CDockWidget标题名称不能重复，不然恢复布局时，重复的名称会只显示一个窗口控件；
2. CDockWidget需要设置控件，不然恢复布局时，都会消失；
3. 如果需要向某一Dock设置平行布局，需设置ads::DockWidgetArea::CenterDockWidgetArea;
4. 恢复布局后，之前绑定的信号和槽有的可能就失效了；
5. 上下布局时，是均分的，如需设置窗口显示比例，需调用CDockManager类中的void setSplitterSizes(CDockAreaWidget *ContainedArea, const QList<int>& sizes)函数；
6. 使用此模块时，若自由化程度较高，则出Bug的概率就会随之提升。