Qt Widgets 之 QDockWidget（停靠窗口）

目录

什么是停靠窗口

如何添加停靠窗口

QDockWidget::setWidget()

QMainWindow::addDockWidget()

设置停靠选项 (Options)

AnimatedDocks

AllowNestedDocks

AllowTabbedDocks

ForceTabbedDocks

VerticalTabs

GroupedDragging

设置窗口特性 (Features)

设置可停靠区域

设置角落区域

分割窗口

标签页显示 (tab)

设置窗口标题栏

保存停靠窗口状态

常见问题

拓展阅读

Application Example

Dock Widgets Example

MDI Example

Menus Example

SDI Example 

---

什么是停靠窗口

在 Qt 中，停靠窗口 (dock window) 都是 QDockWidget 的实例，可以停靠在 QMainWindow 的中央部件 (central widget) 的上下左右四个区域，停靠的 QDockWidget 没有框架，有一个较小的标题栏；也可浮动出来作为独立窗口。

QDockWidget API 允许程序员控制停靠窗口移动、浮动和关闭的能力，以及它们可以放置的区域等。

相关文档：QDockWidget Class，QMainWindow Class

Qt 提供了很多相关示例，其中 Main Window 最为全面详细，我们今天就就着这个示例研究一下 QDockWidget 的用法及特性。

如何添加停靠窗口

先看一段代码关于如何创建停靠窗口，并将其添加到主窗口：

    QDockWidget *dockWidget = new QDockWidget(tr("Dock Widget"), this);
    dockWidget->setAllowedAreas(Qt::LeftDockWidgetArea | Qt::RightDockWidgetArea);
    dockWidget->setWidget(dockWidgetContents);
    addDockWidget(Qt::LeftDockWidgetArea, dockWidget);

QDockWidget::setWidget()

void QDockWidget::setWidget(QWidget *widget) 

QDockWidget 充当该 widget 的包装器。注意：调用这个函数之前必须为 widget 添加布局，否则它将不可见，而且如果此时 QDockWidget 已经可见了，那我们必须显式地 widget->show() 。

QMainWindow::addDockWidget()

void QMainWindow::addDockWidget(Qt::DockWidgetArea area, QDockWidget *dockwidget)

使用这个函数可以为 QMainWindow 在指定区域（上/下/左/右）添加一个停靠窗口。

设置停靠选项 (Options)

void QMainWindow::setDockOptions(QMainWindow::DockOptions options)

该函数可设置停靠窗口的一些行为。QMainWindow::DockOptions 是枚举类型，定义为：

    enum DockOption {
        AnimatedDocks = 0x01,
        AllowNestedDocks = 0x02,
        AllowTabbedDocks = 0x04,
        ForceTabbedDocks = 0x08,  // implies AllowTabbedDocks, !AllowNestedDocks
        VerticalTabs = 0x10,      // implies AllowTabbedDocks
        GroupedDragging = 0x20    // implies AllowTabbedDocks
    };
    Q_ENUM(DockOption)
    Q_DECLARE_FLAGS(DockOptions, DockOption)
    Q_FLAG(DockOptions)

默认值： AnimatedDocks | AllowTabbedDocks. 

注意：这些选项仅控制如何在 QMainWindow 中放置停靠窗口，它们不会重新排列已有的停靠窗口以符合指定的选项。因此，应在停靠窗口添加到主窗口之前设置它们。 AnimatedDocks 和 VerticalTabs 选项除外，它们可以随时设置。

AnimatedDocks

默认设置该选项，对停靠窗口和工具栏的操作进行动画处理。当在主窗口上拖动停靠窗口或工具栏时，主窗口会调整其内容以指示窗口在放置时停靠的位置，这一过程以平滑的动画移动。若清除该选项则无动画效果。

同 animated 属性，查询及设置函数：
bool isAnimated() const
void setAnimated(bool enabled)

注意：如果主窗口有的 widgets 在调整大小或重新绘制自身时很缓慢，则该属性可能会被清除。

AllowNestedDocks

默认不设置该选项，每个停靠区域只能包含单行停靠窗口（即垂直方向的停靠区域只有一列，水平区域的停靠区域只有一行）；若设置该属性，则停靠区域可以在任一方向拆分以包含更多停靠窗口（即垂直方向的停靠区域可以有多列，水平方向的停靠区域可以有多行）。

同 dockNestingEnabled 属性，查询及设置函数：
bool isDockNestingEnabled() const
void setDockNestingEnabled(bool enabled)

注意：仅在包含大量停靠窗口的应用程序中才需要设置该属性&#