Qt-Advanced-Docking-System: 一个基于 Qt 框架的高级停靠窗口系统
目录
1.简介
2.主要特性
3.安装与集成
4.基本使用流程
5.高级功能
6.应用场景
7.注意事项
1.简介
Qt-Advanced-Docking-System（简称 QADS）是一个基于 Qt 框架的高级停靠窗口系统，专为需要复杂窗口布局管理的应用程序设计（如 IDE、CAD 软件、数据分析工具等）。它扩展了 Qt 原生QDockWidget的功能，提供了更灵活、更贴近现代 UI 设计的停靠体验，类似 Visual Studio、Qt Creator 等专业软件的窗口管理效果。
对比 Qt 原生 QDockWidget具有以下优势：
1.更丰富的停靠方式
支持窗口在主窗口边缘、内部面板、甚至其他窗口上的任意停靠，可形成标签页式组合、分割式布局等。
2.高级拖拽交互
拖拽时显示实时布局预览（如停靠区域高亮），支持窗口脱离主窗口成为独立浮动窗口，且浮动窗口可重新停靠。
3.布局持久化
内置布局保存 / 恢复功能，可将当前窗口布局（位置、大小、状态）保存到配置文件，下次启动时自动恢复。
4.高度自定义
支持自定义标题栏、图标、样式表，可根据需求调整窗口边框、拖拽灵敏度等交互细节。
5.多文档界面（MDI）支持
可与 Qt 的 MDI 框架结合，实现停靠窗口与多文档界面的混合布局。
2.主要特性
1.停靠区域
支持上、下、左、右、中心区域及窗口间的嵌套停靠。随处停靠，无中央部件，不像 Qt 停靠系统中那样的中央部件。您可以停靠在主窗口的每一条边框上，也可以停靠到每一个停靠区域中因此，您几乎可以自由地在任何位置进行停靠。
2.浮动窗口内停靠
主窗口与浮动窗口之间不存在差异，支持向浮动窗口内进行停靠。
3.分组拖动
多个停靠窗口可在同一区域形成标签页，类似浏览器标签。拖动一个停靠栏的标题栏时，与其处于同一标签组的所有标签都将随之拖动。这样一来，您可以将整个标签组部件移动到一个浮动部件中，或者从一个停靠区域移动到另一个停靠区域。
4.用于快速切换完整主窗口布局的视图
视角定义了主窗口中停靠窗口的集合和布局。您可以将停靠管理器的当前布局保存到一个命名视角中，以创建自己的自定义视角。之后，您只需从视角列表中选择一个视角，即可快速切换整个主窗口布局。
5.不透明和透明拆分器调整大小
先进的停靠系统使用标准的QSplitter作为大小调整分隔符，因此支持QSplitter的不透明和透明调整大小功能。在某些罕见情况下，对于非常复杂的小部件或在速度较慢的机器上，通过分隔符实时调整大小可能会导致小部件内的渲染内容出现闪烁和刺眼现象。全局停靠管理器标志OpaqueSplitterResize用于配置分隔符的调整大小行为。如果设置了此标志，那么在交互式移动分隔符时，小部件会动态（不透明地）调整大小。
如果清除此标志，窗口部件的大小调整将延迟到鼠标按钮释放后进行——这是一种延迟调整大小的分隔符。
6.可取消的停靠过程
与标准的Qt停靠系统不同，使用ADS进行停靠的操作更类似于拖放操作。这意味着，被拖动的停靠部件或停靠区域不会立即脱离停靠状态。相反，系统会创建一个拖动预览部件并随拖动移动，以指示该停靠部件或停靠区域的未来位置。实际的停靠操作只有在释放鼠标按钮时才会执行。这使得通过Esc键取消正在进行的拖动操作成为可能。
拖放预览窗口小部件可通过多个全局停靠管理器标志进行配置：
DragPreviewIsDynamic: 如果启用此标志，预览将动态调整以适应放置区域DragPreviewShowsContentPixmap: 创建的拖放预览窗口显示被拖动的停靠部件/停靠区域内容的静态副本DragPreviewHasWindowFrame: 此标志用于配置拖动预览是像QRubberBand一样无边框，还是看起来像真实窗口。
7.标签菜单，便于处理多个带标签的停靠部件
标签页是在停靠区域中快速切换停靠窗口的好方法。不过，如果停靠区域中的停靠窗口数量过多，可能会影响标签栏的可用性。在这种情况下，为了便于管理，您可以使用标签菜单。该菜单允许您从下拉菜单中快速选择想要激活的停靠窗口。
8.分离停靠窗口部件的多种不同方式
您可以通过以下方式分离停靠窗口部件和停靠区域：
- 通过拖动停靠部件标签或停靠区域标题栏
- 通过双击标签页或标题栏
- 通过使用选项卡和标题栏下拉菜单中的分离菜单项
9.支持删除动态创建的停靠部件
通常情况下，点击停靠窗口的关闭按钮只会隐藏该窗口，用户可以通过停靠窗口的toggleView()操作再次显示它。这适用于包含固定数量窗口的用户界面。但高级停靠系统也支持动态停靠窗口，这类窗口在关闭时会被删除。如果为某个停靠窗口设置了停靠窗口标志DockWidgetDeleteOnClose，那么关闭该停靠窗口时，它就会立即被删除。这使得能够实现带有动态创建编辑器的用户界面，例如在文字处理应用程序或源代码开发工具中。
10.事件通知
提供丰富的信号（如窗口移动、停靠状态变化、布局改变），便于业务逻辑联动。
11.跨平台兼容
支持 Windows、Linux、macOS，与 Qt 5.x/6.x 版本兼容。
3.安装与集成
QADS 是开源库（MIT 许可证），源码托管于 GitHub：github.com/githubuser0xFFFF/Qt-Advanced-Docking-System
集成步骤：
1.获取源码
克隆仓库或下载 release 包，包含头文件、源文件及示例项目。
2.Qt 项目
直接打开ads.pro工程，编译即可。
如果是CMake系统，通过add_subdirectory引入。
3.依赖
需启用 Qt 的Widgets模块，部分功能依赖Gui模块。
4.基本使用流程
1.初始化停靠管理器
首先在主窗口中创建DockManager实例（核心管理器）：
#include "ads/CDockManager.h"// 在主窗口构造函数中
MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent) {// 初始化停靠管理器，关联主窗口m_dockManager = new ads::CDockManager(this);// 设置主窗口中央部件（非必须，若需中心区域内容）setCentralWidget(new QTextEdit("中央内容区域"));
}2.创建停靠窗口
通过CDockWidget创建停靠窗口，并添加到管理器：
#include "ads/CDockWidget.h"// 创建一个停靠窗口
ads::CDockWidget* dockWidget = new ads::CDockWidget("属性窗口");
// 设置窗口内容（任意QWidget派生类）
dockWidget->setWidget(new QTreeWidget());
// 将窗口添加到管理器（默认停靠在右侧）
auto dockArea = m_dockManager->addDockWidget(ads::RightDockWidgetArea, dockWidget);3.控制停靠行为
可通过setAllowedAreas限制窗口可停靠的区域：
// 只允许在左侧或右侧停靠
dockWidget->setAllowedAreas(ads::LeftDockWidgetArea | ads::RightDockWidgetArea);4.保存与恢复布局
// 保存布局到文件
m_dockManager->saveStateToFile("layout.json");// 恢复布局（程序启动时）
if (QFile::exists("layout.json")) {m_dockManager->loadStateFromFile("layout.json");
}5.入门示例
下面的示例展示了使用高级Qt停靠系统所需的最少代码。
MainWindow.h
#include <QMainWindow>
#include "DockManager.h"namespace Ui {
class MainWindow;
}class MainWindow : public QMainWindow
{Q_OBJECTpublic:explicit MainWindow(QWidget *parent = 0);~MainWindow();private:Ui::MainWindow *ui;// The main container for dockingads::CDockManager* m_DockManager;
};主窗口：MainWindow.cpp
#include "MainWindow.h"
#include "ui_MainWindow.h"#include <QLabel>MainWindow::MainWindow(QWidget *parent) :QMainWindow(parent),ui(new Ui::MainWindow)
{ui->setupUi(this);// Create the dock manager after the ui is setup. Because the// parent parameter is a QMainWindow the dock manager registers// itself as the central widget as such the ui must be set up first.DockManager = new ads::CDockManager(this);// Create example content label - this can be any application specific// widgetQLabel* l = new QLabel();l->setWordWrap(true);l->setAlignment(Qt::AlignTop | Qt::AlignLeft);l->setText("Lorem ipsum dolor sit amet, consectetuer adipiscing elit. ");// Create a dock widget with the title Label 1 and set the created label// as the dock widget contentads::CDockWidget* DockWidget = DockManager->createDockWidget("Label 1");DockWidget->setWidget(l);// Add the toggleViewAction of the dock widget to the menu to give// the user the possibility to show the dock widget if it has been closedui->menuView->addAction(DockWidget->toggleViewAction());// Add the dock widget to the top dock widget areaDockManager->addDockWidget(ads::TopDockWidgetArea, DockWidget);
}MainWindow::~MainWindow()
{delete ui;
}5.高级功能
1.自定义样式
通过CDockManager::setStyleSheet或继承CDockStyle自定义外观：
// 简单样式示例：修改标题栏背景
m_dockManager->setStyleSheet(R"(ads--CDockWidgetTitleBar {background-color: #2d2d2d;color: white;}ads--CDockWidgetTitleBar:checked {background-color: #4a90e2;}
)");2.窗口分组与标签页
多个窗口可合并为标签页：
// 创建第二个窗口
ads::CDockWidget* dock2 = new ads::CDockWidget("日志窗口");
dock2->setWidget(new QTextEdit());
// 将第二个窗口添加到第一个窗口的同一区域，自动形成标签页
m_dockManager->addDockWidget(ads::RightDockWidgetArea, dock2, dockWidget);3.事件监听
监听窗口状态变化：
// 窗口停靠状态变化时触发
connect(dockWidget, &ads::CDockWidget::dockLocationChanged, this, [](ads::CDockWidget::DockLocation location) {qDebug() << "窗口位置变化：" << location;
});6.应用场景
- 集成开发环境（IDE）：如代码编辑器、控制台、属性面板的布局管理。
- 数据分析工具：图表窗口、参数面板、数据列表的灵活排列。
- 工程软件：工具栏、属性面板、预览窗口的动态布局。
7.注意事项
- 版本兼容性：Qt 5.9 + 及 Qt 6.x 需对应不同的 QADS 版本，需注意匹配。
- 性能：复杂布局下建议避免过多嵌套窗口，以免影响渲染效率。
- 文档：官方文档较简洁，建议参考源码中的
examples目录（包含多个演示案例）。
总之，Qt-Advanced-Docking-System 是 Qt 生态中功能最完善的停靠窗口解决方案之一，适合需要专业级窗口布局的应用开发，显著提升用户对界面的掌控感和操作效率。