一、概述
QDockWidget類提供了一個可以停靠在QMainWindow中或作爲桌面上的頂級窗口浮動的部件。停靠窗口(Dock windows)是放置在QMainWindow主窗口中央窗口部件(Central widget)周圍的次要窗口，如下圖中央部件周圍的白色區域，這塊區域老猿稱爲停靠區域。
根據停靠窗口的屬性設置，停靠窗口可以在停靠區域內移動，移動到新區域並由最終用戶確定是否浮動。
QDockWidget對象由一個標題欄和內容區域組成。標題欄顯示停靠窗口標題、浮動按鈕（
）和關閉按鈕。根據QDockWidget的設置，這兩個按鈕可能被禁用或根本不顯示。
QDockWidget的內容區域，實際上是一個它包含的子部件，停靠窗口展示的內容即該子部件的內容，該子部件必須是QWidget或其派生類。
二、QDockWidget的重要屬性及關聯信號
2.1、Designer中QDockWidget的屬性
在Designer中，QDockWidge有如下屬性：
2.2、屬性及關聯信號介紹
2.2.1、floating屬性
floating屬性表示QDockWidget對象是否浮動在主窗口之上，如果爲True表示浮動停靠部件作爲漂浮在其父QMainWindow的“頂部”使用獨立窗口展現，爲False則停靠在在QMainWindow中。缺省爲True，可通過方法isFloating()、setFloating(bool
floating)來訪問該屬性，當此屬性改變時，會發射 topLevelChanged(bool floating) 信號，信號簽名表示QDockWidget對象現狀是否浮動在主窗口之上
2.2.2、features屬性
features屬性用於設置浮動部件的特徵，其類型爲枚舉類型 QDockWidget.DockWidgetFeatures,特徵包括浮動窗是否可關閉（DockWidgetClosable）、是否可移動（DockWidgetMovable）、是否可浮動（DockWidgetFloatable）、是否將標題欄展示在窗口左邊成豎直標題欄（DockWidgetVerticalTitleBar）。除了這幾個值之外，該特徵類型在Designer中還有如下取值：
- AllDockWidgetFeatures：表示同時設置了DockWidgetClosable、DockWidgetMovable、DockWidgetFloatable這三個特徵，但不一定設置了DockWidgetVerticalTitleBar特徵，但不建議使用這個值，因爲Qt或PyQt可能會增加其他特徵值時，AllDockWidgetFeatures包括的特徵範圍可能會增加
- DockWidgetFeatureMask：表示同時設置了DockWidgetClosable、DockWidgetMovable、DockWidgetFloatable、DockWidgetVerticalTitleBar這四個特徵，這個DockWidgetFeatureMask值僅在Designer中使用，選擇這個特徵則自動勾選上述四個特徵，但在類中無此枚舉值，即代碼不識別該值；
- NoDockWidgetFeatures：表示不設置任何特徵，在Designer中選擇此值自動去掉其他特徵，由於此值對應數值爲0，代碼中如果使用此值與其他值組合，則此值將失效，以其他值爲準
- Reserved：這個值在Designer中選擇後，將會勾選所有除NoDockWidgetFeatures之外的特徵值，但該值在代碼中無效。
features屬性缺省爲 DockWidgetClosable, DockWidgetMovable和DockWidgetFloatable的組合，可通過方法features() 和setFeatures(DockWidgetFeatures features)訪問該屬性。
當features屬性修改時，會發射featuresChanged(QDockWidget.DockWidgetFeatures features)信號。
2.2.3、allowedAreas屬性
allowedAreas屬性用於控制停靠部件在QMainWindow的停靠區域中可停靠的範圍，其類型爲枚舉類型Qt.DockWidgetArea或其值的組合，分別控制可以停靠在主窗口停靠區域的左邊（LeftDockWidgetArea）、右邊（RightDockWidgetArea）、頂部（TopDockWidgetArea）、底部（BottomDockWidgetArea）、所有區域（AllDockWidgetAreas）和不能停靠（NoDockWidgetArea）。
allowedAreas屬性缺省值爲AllDockWidgetAreas，即所有區域都可以停靠，可以通過allowedAreas()和setAllowedAreas(Qt.DockWidgetAreas areas)來訪問該屬性。
allowedAreas屬性發生變更時，QDockWidget會發射allowedAreasChanged(Qt.DockWidgetAreas allowedAreas)信號。
2.2.4、dockWidgetArea和docked屬性
dockWidgetArea和docked屬性這兩個屬性在Designer中有設置，dockWidgetArea表示部件的初始停靠位置，取值範圍和allowedAreas相同，docked爲布爾值，表示是否啓用停靠功能，但這兩個屬性QDockWidget都沒有，實際上是用於控制調用QMainWindow的addDockWidget方法，當docked爲True時，Designer生成的代碼就會調用QMainWindow的addDockWidget方法，addDockWidget第一個參數即爲Designer屬性的dockWidgetArea，當docked爲False時，Designer生成的代碼就不會調用QMainWindow的addDockWidget方法。
三、QDockWidget的其他重要方法
除了與屬性相關的方法外，QDockWidget還有幾個比較重要的方法。
3.1、isAreaAllowed方法
isAreaAllowed方法用於判斷QMainWindow的某個停靠區域是否允許停靠，調用語法如下：
bool isAreaAllowed(Qt.DockWidgetArea area)
3.2、setTitleBarWidget方法
setTitleBarWidget方法用於給停靠窗口設置個性化的標題欄，調用語法如下：
setTitleBarWidget(QWidget widget)
說明：
- widget參數可以是任意一個QWidget 或其派生類對象，如果傳None，則將原來通過setTitleBarWidget設置的部件取消了，使用缺省的窗口標題代替
- 如果設置了一個有效的QWidget 或其派生類對象作爲標題欄，在浮動時不會使用本機窗口裝飾（包括關閉按鈕），而是使用參數部件作爲標題
- 如果無法直接刪除浮動窗口的標題欄，可以使用QWidget（）不帶參數方式構建一個QWidget對象實現相同的效果
- 使用titleBarWidget()方法可以返回該停靠窗口使用的標題欄部件。
3.3、widget和setWidget方法
在概述部分介紹了，QDockWidget對象由一個標題欄和內容區域組成。QDockWidget的內容區域，實際上是一個它包含的子部件，浮動窗口展示的內容即該子部件的內容，該子部件必須是QWidget或其派生類。方法widget和setWidget就是用於訪問QDockWidget的內容區域對應的子部件。調用語法如下：
setWidget(QWidget widget)QWidget widget()
3.4、toggleViewAction方法
toggleViewAction方法返回一個動作對象，該動作對象通過點擊後可以切換停靠窗口的可見狀態，即該動作是一個對停靠部件窗口顯示或關閉的開關，如果將該動作加到菜單上，對應菜單欄的文字即爲停靠窗口的title文字，這樣就可以在菜單上點擊對應菜單項進行停靠窗口的關閉和顯示，這個關閉和顯示的狀態在QMainWindow的快捷菜單中就有這樣的功能。下圖是QMainWindow的停靠窗口開關狀態快捷菜單以及將部分停靠窗口（字體設置、機器人發言字體顏色、本機輸入發言字體顏色）對應開關動作加到菜單欄的一個案例截圖：
上圖中有2個停靠窗口是關閉的，如果所有停靠窗全部顯示則如下效果：
上圖中黃色標記的標籤選項欄對應三個停靠窗。
四、QDockWidget的信號
除了前面介紹屬性的時候介紹的信號allowedAreasChanged、featuresChanged、topLevelChanged外，QDockWidget還有2個信號：dockLocationChanged、visibilityChanged。
dockLocationChanged信號在QDockWidget停靠位置因手工拖拽或代碼執行導致停靠位置發生變化時發射，包括移動到不同停靠區域或同一停靠區域的不同位置都會發射該信號。信號語法：dockLocationChanged(Qt.DockWidgetArea area)
visibilityChanged信號在QDockWidget可見狀態發生變化時發射，這種可見狀態發生變化包括顯示或隱藏窗口以及QDockWidget對象停靠在選項卡區域時QDockWidget對象對應選項被選中或去選中時。信號語法：visibilityChanged(bool visible)
五、QMainWindow與QDockWidget相關的操作方法以及信號
5.1、引言
QDockWidget除了放在QMainWindow窗口內外，也可以放在其他類型的窗體如QWidget窗口內，但QMainWindow提供了與QDockWidget配套的特性如停靠區域，而其他窗口沒有配套特性，QDockWidget在其他窗口中也可以浮動，但拖拽時無法自動停靠，只能通過鼠標雙擊標題欄回到原始位置。
QMainWindow與QDockWidget相關的特性處理停靠區域的支持外，還提供了與停靠窗口相關的：
- 三個屬性：animated、dockNestingEnabled、dockOptions
- 八個方法：addDockWidget、dockWidgetArea、removeDockWidget、resizeDocks、restoreDockWidget、splitDockWidget、tabifiedDockWidgets、tabifyDockWidget
- 一個信號：tabifiedDockWidgetActivated
其中三個屬性已經在《第15.11節 PyQt（Python+Qt）入門學習：Qt Designer（設計師）組件Property Editor（屬性編輯）界面中主窗口QMainWindow類相關屬性詳解》進行了介紹，在此不重複介紹。
5.2、addDockWidget方法
QMainWindow的addDockWidget方法用於將對應停靠窗增加到指定區域，調用語法如下：
- addDockWidget(Qt.DockWidgetArea area, QDockWidget dockwidget)
- addDockWidget(Qt.DockWidgetArea area, QDockWidget dockwidget, Qt.Orientation orientation)
參數area用於指定QDockWidget對象的初始停靠區域，orientation確認標題欄是位於頂部水平方向，還是位於左邊豎直方向。
5.3、resizeDocks
resizeDocks用於將QMainWindow的多個停靠窗的大小進行調整，調用語法如下：
resizeDocks( Iterable[QDockWidget], Iterable[int], Qt.Orientation)
參數說明：
- Iterable[QDockWidget]：需要調整的多個停靠窗對象組成的迭代類型如列表
- Iterable[int]：每個停靠窗需要調整的寬度或高度
- Qt.Orientation：調整的是寬度還是高度，如果爲Qt.Horizontal，調整寬度，否則調整高度
注意：
- 大小的調整受最小和最大大小的約束
- 大小調整不會影響主窗口的大小
- 如果空間有限的情況下，調整時根據各個停靠窗口的相對大小佔比進行可以利用空間的調整
5.4、tabifyDockWidget
主窗口的tabifyDockWidget方法用於將主窗口的兩個停靠窗口創建一個選項卡式的停靠區域。調用語法：
tabifyDockWidget(QDockWidget first, QDockWidget second)
該方法將將second停靠窗移動到first停靠窗的頂部，在主窗口中創建一個選項卡式停靠區域。如圖：
上圖熒光筆標記部分爲選項卡，藍色標記部分爲停靠窗的內容區域，二者加起來就是一個選項卡式停靠區域，兩個停靠窗可以點擊下面的選項卡切換。
5.5、splitDockWidget
主窗口的splitDockWidget方法用於將一個停靠窗佔據的空間分割成兩部分，原有停靠窗放置在第一部分的區域，另一個停靠窗放置在第二部分的區域。調用語法：
splitDockWidget( QDockWidget first, QDockWidget second, Qt.Orientation orientation)
說明：
- orientation：指定分割方向，是水平分隔還是垂直分隔，如果水平分隔，則這兩個停靠窗水平方向並列，first在左second在右，如果是垂直分隔，則兩個停靠窗上下排列，first在上second在下
- 如果第一個停靠窗已經是選項卡化停靠窗，則第二個停靠窗將作爲新選項卡添加，而不是作爲第一個的鄰居，這是因爲單個選項卡只能包含一個停靠部件，此時splitDockWidget的效果與tabifyDockWidget效果相同
- splitDockWidget實際使用時更多的是用於排列相關停靠窗口使用，也即對停靠窗口通過代碼進行排列調整
5.6、其他方法簡介
QMainWindow的其他4個與QDockWidget相關的方法dockWidgetArea、removeDockWidget、 restoreDockWidget、tabifiedDockWidgets功能非常簡單：
- Qt.DockWidgetArea dockWidgetArea(QDockWidget dockwidget)
用於返回dockwidget停靠窗的停靠區，如果dockwidget未加到主窗口中，則返回Qt.NoDockWidgetArea。 - removeDockWidget(QDockWidget dockwidget)
用於將主窗口中的停靠窗dockwidget移除並隱藏它，但dockwidget對象並未釋放，還可以繼續使用 - bool restoreDockWidget(QDockWidget dockwidget)
將dockwidget恢復成初始創建狀態，成功返回True，否則返回False。 - list[QDockWidget] tabifiedDockWidgets(QDockWidget dockwidget)
返回與參數dockwidget指定停靠窗一起成選項卡式排列的所有停靠窗列表。
5.7、tabifiedDockWidgetActivated信號
tabifiedDockWidgetActivated信號爲主窗口中的選項卡式排列的停靠窗被選中激活時發射，被激活的停靠窗爲信號簽名參數。語法如下：
QMainWindow.tabifiedDockWidgetActivated(QDockWidget dockWidget)
六、小結
本章節詳細介紹了QDockWidget的屬性、方法、信號以及主窗口與QDockWidget相關的屬性、方法和信號，由於主窗口提供了對停靠窗口豐富的支撐能力，才使得通過主窗口可以構建友好的用戶界面。
廣告
老猿關於PyQt的付費專欄《使用PyQt開發圖形界面Python應用》只需要9.9元，該部分與第十五章的內容基本對應，但同樣內容在付費專欄上總體來說更詳細、案例更多。本節內容對應付費專欄的《第三十一章、containers容器類部件QDockWidget停靠窗功能介紹》。如果有興趣也願意支持老猿的讀者，歡迎購買付費專欄。
