QDockWidget 是 Qt 中的一个控件类

QDockWidget 是 Qt 中的一个控件类，用于实现可停靠的窗口部件（dockable windows）。它允许用户将窗口拖动到主窗口的不同区域，或将其浮动在主窗口外部。通常与 QMainWindow 一起使用，QMainWindow 提供了内置的布局机制，可以将 QDockWidget 部署在主窗口的不同位置。

QDockWidget 的典型应用场景包括开发环境中的工具栏、侧边栏等，用户可以通过拖拽自由调整这些窗口的位置或将其隐藏。

QDockWidget 的主要属性

1. 标题 (Title)

   • windowTitle: 用于设置停靠窗口的标题栏显示的文本。
   • setWindowTitle(title): 设置停靠窗口的标题。

2. 停靠状态 (Docking State)

   • isFloating(): 返回 True 或 False，表示窗口是否是浮动状态。
   • setFloating(bool): 设置停靠窗口是否应浮动。True 代表浮动，False 代表停靠在主窗口中。

3. 区域控制 (Dock Area)

   • allowedAreas(): 返回停靠窗口允许被放置的区域，如 Qt.LeftDockWidgetArea, Qt.RightDockWidgetArea, Qt.TopDockWidgetArea 或 Qt.BottomDockWidgetArea。
   • setAllowedAreas(Qt.DockWidgetArea): 设置停靠窗口允许停靠的区域。
   • toggleViewAction(): 返回一个 QAction 对象，允许用户显示或隐藏此停靠窗口（通常用于菜单项或工具栏按钮中）。

4. 特性控制 (Features)

   • features(): 返回停靠窗口的功能（是否允许关闭、移动、浮动等）。
   • setFeatures(QDockWidget.DockWidgetFeatures): 设置停靠窗口的功能特性，可以组合使用如 QDockWidget.DockWidgetClosable, QDockWidget.DockWidgetMovable, QDockWidget.DockWidgetFloatable 等选项。

5. 可见性 (Visibility)

   • isVisible(): 返回窗口是否可见。
   • setVisible(bool): 显示或隐藏停靠窗口。

主要接口函数

1. setWidget(widget)

   • 这个函数用于将一个 QWidget 作为 QDockWidget 的主控件。通过 setWidget()，可以设置一个具体的控件（如表单、文本编辑器等）作为停靠窗口的内容。
   • 示例：

     dockWidget.setWidget(myWidget)
     

2. widget()

   • 返回当前设置的主控件，即停靠窗口中包含的 QWidget。
   • 示例：

     contentWidget = dockWidget.widget()
     

3. setTitleBarWidget(widget)

   • 设置自定义的标题栏控件，替换掉默认的标题栏。
   • 示例：

     dockWidget.setTitleBarWidget(customTitleBarWidget)
     

4. titleBarWidget()

   • 返回自定义的标题栏控件。
   • 示例：

     titleBar = dockWidget.titleBarWidget()
     

5. toggleViewAction()

   • 返回一个 QAction，该动作可以用于在菜单中显示或隐藏停靠窗口。
   • 示例：

     menu.addAction(dockWidget.toggleViewAction())
     

信号 (Signals)

1. topLevelChanged(bool)

   • 当停靠窗口的浮动状态发生变化时发出信号（例如从停靠状态变为浮动状态，或从浮动状态恢复到停靠状态）。
   • 示例：

     dockWidget.topLevelChanged.connect(myHandlerFunction)
     

2. visibilityChanged(bool)

   • 当停靠窗口的可见性发生变化时发出信号。
   • 示例：

     dockWidget.visibilityChanged.connect(myHandlerFunction)
     

示例代码

import sys
from PyQt5.QtWidgets import QApplication, QMainWindow, QTextEdit, QDockWidget

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()

        # 创建主控件
        self.editor = QTextEdit()
        self.setCentralWidget(self.editor)

        # 创建一个 QDockWidget
        self.dockWidget = QDockWidget("Dockable", self)
        self.dockWidget.setAllowedAreas(Qt.LeftDockWidgetArea | Qt.RightDockWidgetArea)

        # 设置停靠窗口的主控件
        self.dockWidget.setWidget(QTextEdit())
        self.addDockWidget(Qt.RightDockWidgetArea, self.dockWidget)

if __name__ == "__main__":
    app = QApplication(sys.argv)
    mainWindow = MainWindow()
    mainWindow.show()
    sys.exit(app.exec_())

运行效果：

• 在 QMainWindow 中，主窗口中央放置了一个 QTextEdit 文本编辑器。
• 右侧是一个可以停靠的 QDockWidget，它也是一个 QTextEdit。
• 用户可以将 QDockWidget 拖动到窗口的不同区域，或将其浮动在主窗口外。

常见用途

• 在 IDE 或开发工具中，将工具窗口（如文件浏览器、输出控制台、属性面板等）设计成可以浮动或停靠的方式。
• 在复杂的图形用户界面中，用户可以自由调整窗口的布局。
  是的，QDockWidget 支持在停靠后隐藏的功能。你可以通过以下几种方式来实现这一功能：

1. 通过 QDockWidget::hide() 来隐藏停靠窗口

当 QDockWidget 停靠在主窗口中时，可以直接调用 hide() 方法将其隐藏起来，这样它将从界面中消失，直到你调用 show() 方法将其重新显示。

示例：

dockWidget.hide()  # 隐藏
dockWidget.show()  # 显示

2. 通过 toggleViewAction() 实现菜单控制

QDockWidget 提供了 toggleViewAction() 函数，该函数返回一个 QAction 对象，可以将其添加到菜单或工具栏中。这使得用户可以通过菜单项来显示或隐藏 QDockWidget。

示例：

# 创建一个菜单栏并添加停靠窗口的显示/隐藏控制项
menu = self.menuBar().addMenu("View")
menu.addAction(self.dockWidget.toggleViewAction())

这允许用户从菜单中选择是否显示或隐藏停靠窗口。

3. 自动隐藏（折叠式停靠窗口）

Qt 并没有内置支持像一些 IDE 中那种 “自动隐藏” 或 “折叠” 功能（即当窗口不使用时自动隐藏，只在鼠标悬停时显示），但你可以通过一些自定义的处理来模拟这一功能。

4. 响应 visibilityChanged(bool) 信号

QDockWidget 有一个 visibilityChanged 信号，当窗口显示状态发生变化时会触发该信号。你可以使用这个信号在窗口隐藏时执行其他操作，例如在窗口隐藏时调整布局。

示例：

def on_visibility_changed(visible):
    if visible:
        print("Dock widget is visible")
    else:
        print("Dock widget is hidden")

dockWidget.visibilityChanged.connect(on_visibility_changed)

5. 用户双击标题栏来隐藏和显示

默认情况下，用户可以通过双击 QDockWidget 的标题栏，将其从浮动状态切换到隐藏状态或停靠状态。在标题栏上点击关闭按钮（如果 QDockWidget 设置了 Closable 特性），也可以直接关闭窗口，这也会隐藏该窗口。

综合示例代码

import sys
from PyQt5.QtWidgets import QApplication, QMainWindow, QTextEdit, QDockWidget, QMenuBar

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()

        # 创建主控件
        self.editor = QTextEdit()
        self.setCentralWidget(self.editor)

        # 创建一个 QDockWidget
        self.dockWidget = QDockWidget("Dockable", self)
        self.dockWidget.setAllowedAreas(Qt.LeftDockWidgetArea | Qt.RightDockWidgetArea)

        # 设置停靠窗口的主控件
        self.dockWidget.setWidget(QTextEdit())
        self.addDockWidget(Qt.RightDockWidgetArea, self.dockWidget)

        # 创建菜单项来控制显示/隐藏
        menu = self.menuBar().addMenu("View")
        menu.addAction(self.dockWidget.toggleViewAction())

        # 信号连接
        self.dockWidget.visibilityChanged.connect(self.on_visibility_changed)

    def on_visibility_changed(self, visible):
        if visible:
            print("Dock widget is visible")
        else:
            print("Dock widget is hidden")

if __name__ == "__main__":
    app = QApplication(sys.argv)
    mainWindow = MainWindow()
    mainWindow.show()
    sys.exit(app.exec_())

在这个示例中：

• 通过菜单可以控制 QDockWidget 的显示或隐藏。
• visibilityChanged 信号用于监视窗口是否处于可见状态，可以在窗口隐藏或显示时做额外的处理。