Qt之容器控件（QDockWidget）

简述

QDockWidget类提供了一个小部件，它可以停靠在QMainWindow内，也可以作为桌面上的顶层窗口浮动。

功能详述

QDockWidget提供了铆接（停靠）控件的概念，也叫做工具窗口。铆接窗口是QMainWindow中心控件的辅助窗口，停放在QMainWindow的铆接区域，铆接区域如下所示：

铆接部件可以在铆接区域移动，或者浮动。QDockWidget提供了API来控制铆接部件的可移动区域。

铆接部件由标题栏和内容主体组成。标题栏显示铆接部件的窗口标题。

QDockWidget用作其子窗口小部件的包装，该子窗口小部件由setWidget()设置。自定义尺寸参考、最大最小尺寸、尺寸策略都应当在子控件中实现。QDockWidget会尊重这些尺寸设置，并调整自身以适应子控件与标题栏。由于铆接部件的变化很大程度上取决于它是否被铆接，因此，尺寸策略不应当被设置在QDockWidget上。

使用

效果

上面的例子展示了铆接部件的基本效果。QTextEdit作为QMainWindow的中心控件，铆接部件可以停靠在QTextEdit的四周。

源码

    QTextEdit *textEdit = new QTextEdit;

    QMainWindow *mainWindow = new QMainWindow;

    QDockWidget *dock = new QDockWidget(tr("Customers"), this);

    QListWidget *customerList = new QListWidget(dock);
    customerList->addItems(QStringList()
            << "John Doe, Harmony Enterprises, 12 Lakeside, Ambleton"
            << "Jane Doe, Memorabilia, 23 Watersedge, Beaton"
            << "Tammy Shea, Tiblanka, 38 Sea Views, Carlton"
            << "Tim Sheen, Caraba Gifts, 48 Ocean Way, Deal"
            << "Sol Harvey, Chicos Coffee, 53 New Springs, Eccleston"
            << "Sally Hobart, Tiroli Tea, 67 Long River, Fedula");
    dock->setWidget(customerList);
    mainWindow->addDockWidget(Qt::RightDockWidgetArea, dock);

    mainWindow->setCentralWidget(textEdit);


    QGridLayout *gridLayout = new QGridLayout;
    gridLayout->addWidget(mainWindow);

    this->setLayout(gridLayout);

注意： 铆接部件只能放在QMainWindow中，这里的最上层类直接继承自QWidget，所以要实例化一个QMainWindow，如果上层类继承自QMainWindow，则可以直接添加铆接部件。

常用设置

设置子控件

铆接控件一般都要设置一个子控件作为核心内容，设置方法如下

dock->setWidget(customerList);

设置允许停靠的区域

dock->setAllowedAreas(Qt::LeftDockWidgetArea | Qt::RightDockWidgetArea);//只允许左右停靠

默认值是Qt::AllDockWidgetAreas，即，可以停靠在任何区域。其它值如下所示

常量	值
Qt::LeftDockWidgetArea	0x1
Qt::RightDockWidgetArea	0x2
Qt::TopDockWidgetArea	0x4
Qt::BottomDockWidgetArea	0x8
Qt::AllDockWidgetAreas	DockWidgetArea_Mask
Qt::NoDockWidgetArea	0

设置铆接部件行为特性

用于设置铆接部件是否可移动、可关闭、可浮动。默认情况下三种行为都允许。

dock->setFeatures(QDockWidget::DockWidgetClosable)

其它常量如下

常量	值	描述
QDockWidget::DockWidgetClosable	0x01	停靠小部件可以关闭。在某些系统上，dock小部件在浮动时始终具有关闭按钮（例如，在MacOS 10.5上）。
QDockWidget::DockWidgetMovable	0x02	用户可以在扩展坞之间移动扩展坞小部件。
QDockWidget::DockWidgetFloatable	0x04	停靠小部件可以与主窗口分离，并作为独立窗口浮动。
QDockWidget::DockWidgetVerticalTitleBar	0x08	停靠小部件的左侧显示垂直标题栏。这可用于增加QMainWindow中的垂直空间。
QDockWidget::AllDockWidgetFeatures	前三个的值或运算	可移动、可关闭、可浮动
QDockWidget :: NoDockWidgetFeatures	0x00	铆接控件不可移动、不可关闭、不可浮动。

让窗口浮动

dock->setFloating(true)

自定义标题栏

自定义一个标题栏（自定义方法见Qt帮助文档），然后通过下列方法放到铆接部件上

dock->setTitleBarWidget(titleBar);

信号槽

信号

名称	描述
allowedAreasChanged	当可移动区域属性变化时触发，参数为新的可移动区域参数
dockLocationChanged	铆接部件位置发生变化时触发，参数为铆接部件新的位置参数
featuresChanged	浮动属性变化时触发，浮动时传递true，否则传递false
visibilityChanged	可见性发生变化时触发，可见时传递true，否则传递false

引用

[1] Qt 助手