PySide6.QtWidgets.QDockWidget¶

class QDockWidget¶

QDockWidget 类提供了一个可以在 QMainWindow 内部停靠或作为桌面上的顶级窗口浮动的小部件。更多…

概要¶

属性¶

allowedAreasᅟ - 可放置停靠小部件的区域
featuresᅟ - 停靠小部件是否可移动、可关闭和可浮动
floatingᅟ - 停靠小部件是否浮动
windowTitleᅟ - 停靠小部件标题（标题）

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，您也可以通过在我们的https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细描述¶

QDockWidget 提供了停靠小部件的概念，也称为工具面板或实用窗口。停靠窗口是放置在QMainWindow中central widget周围的停靠小部件区域中的辅助窗口。

Dock窗口可以在其当前区域内移动，移动到新区域，并且可以由最终用户浮动（例如，取消停靠）。QDockWidget API允许程序员限制Dock小部件的移动、浮动和关闭能力，以及它们可以放置的区域。

外观¶

一个QDockWidget由标题栏和内容区域组成。标题栏显示停靠小部件的window title，一个浮动按钮和一个关闭按钮。根据QDockWidget的状态，浮动和关闭按钮可能被禁用或根本不显示。

标题栏和按钮的视觉外观取决于所使用的style。

QDockWidget 作为其子小部件的包装器，通过 setWidget() 设置。自定义的大小提示、最小和最大尺寸以及尺寸策略应在子小部件中实现。QDockWidget 将尊重这些设置，调整自身的约束以包括框架和标题。不应在 QDockWidget 本身上设置尺寸约束，因为它们会根据是否停靠而变化；停靠的 QDockWidget 没有框架且标题栏较小。

注意

在macOS上，如果QDockWidget具有本机窗口句柄（例如，如果在其上或子窗口上调用了winId()），则由于限制，在取消停靠时将无法拖动停靠窗口。开始拖动将取消停靠窗口的停靠状态，但需要第二次拖动才能移动停靠窗口本身。

另请参阅

QMainWindow

class DockWidgetFeature¶

常量	描述
QDockWidget.DockWidgetClosable	(继承自 `enum.Flag`) 该停靠窗口可以被关闭。
QDockWidget.DockWidgetMovable	用户可以在不同的停靠区域之间移动停靠部件。
QDockWidget.DockWidgetFloatable	停靠窗口可以从主窗口中分离，并作为独立窗口浮动。
QDockWidget.DockWidgetVerticalTitleBar	停靠部件在其左侧显示垂直标题栏。这可以用于增加`QMainWindow`中的垂直空间。
QDockWidget.NoDockWidgetFeatures	停靠窗口小部件无法关闭、移动或浮动。

注意

当使用from __feature__ import true_property时，属性可以直接使用，否则通过访问器函数使用。

property allowedAreasᅟ: Combination of Qt.DockWidgetArea¶

此属性保存停靠小部件可以放置的区域。

默认是 Qt::AllDockWidgetAreas。

另请参阅

DockWidgetArea

Access functions:

allowedAreas()
setAllowedAreas()
信号 allowedAreasChanged()

property featuresᅟ: Combination of QDockWidget.DockWidgetFeature¶

此属性决定停靠小部件是否可移动、可关闭和可浮动。

默认情况下，此属性设置为DockWidgetClosable、DockWidgetMovable和DockWidgetFloatable的组合。

另请参阅

DockWidgetFeature

Access functions:

features()
setFeatures()
信号 featuresChanged()

property floatingᅟ: bool¶

此属性表示停靠小部件是否浮动。

浮动停靠小部件以单个独立窗口的形式呈现给用户，位于其父窗口QMainWindow的“顶部”，而不是停靠在QMainWindow中，或在一组标签式停靠小部件中。

浮动停靠窗口小部件可以单独定位和调整大小，无论是通过编程方式还是通过鼠标交互。

默认情况下，此属性为 true。

当此属性更改时，会发出topLevelChanged()信号。

另请参阅

isWindow() topLevelChanged()

Access functions:

isFloating()
setFloating()
信号 topLevelChanged()

property windowTitleᅟ: str¶

此属性保存停靠小部件的标题（标题）。

默认情况下，此属性包含一个空字符串。

访问函数：

__init__([parent=None[, flags=Qt.WindowFlags()]])¶

Parameters:

parent – QWidget
flags – WindowType 的组合

构造一个带有父级 parent 和窗口标志 flags 的 QDockWidget。该停靠小部件将被放置在左侧停靠小部件区域。

__init__(title[, parent=None[, flags=Qt.WindowFlags()]])

Parameters:

标题 – str
parent – QWidget
flags – WindowType 的组合

构造一个带有父级 parent 和窗口标志 flags 的 QDockWidget。该停靠小部件将被放置在左侧停靠小部件区域。

窗口标题设置为title。当QDockWidget停靠和取消停靠时，使用此标题。它也在QMainWindow提供的上下文菜单中使用。

另请参阅

setWindowTitle()

allowedAreas()¶

Return type:: DockWidgetArea的组合

另请参阅

setAllowedAreas()

属性 allowedAreasᅟ 的获取器。

allowedAreasChanged(allowedAreas)¶

Parameters:: allowedAreas – DockWidgetArea 的组合

当allowedAreas属性发生变化时，会发出此信号。allowedAreas参数给出了属性的新值。

属性 allowedAreasᅟ 的通知信号。

dockLocationChanged(area)¶

Parameters:: 区域 – DockWidgetArea

当停靠窗口部件移动到另一个停靠区域，或者在其当前停靠区域中移动到不同位置时，会发出此信号。当停靠窗口部件以编程方式移动或用户将其拖动到新位置时，会发生这种情况。

features()¶

Return type:: DockWidgetFeature 的组合

另请参阅

setFeatures()

属性 featuresᅟ 的获取器。

featuresChanged(features)¶

Parameters:: 功能 – DockWidgetFeature 的组合

当features属性发生变化时，会发出此信号。features参数给出了属性的新值。

属性 featuresᅟ 的通知信号。

initStyleOption(option)¶

Parameters:: 选项 – QStyleOptionDockWidget

使用来自此QDockWidget的值初始化option。当子类需要一个QStyleOptionDockWidget但不想自己填写所有信息时，此方法非常有用。

另请参阅

initFrom()

isAreaAllowed(area)¶

Parameters:: 区域 – DockWidgetArea
Return type:: 布尔

如果此停靠部件可以放置在给定的area中，则返回true；否则返回false。

isFloating()¶

Return type:: 布尔

属性 floatingᅟ 的获取器。

setAllowedAreas(areas)¶

Parameters:: areas – DockWidgetArea 的组合

另请参阅

allowedAreas()

属性 allowedAreasᅟ 的设置器。

setFeatures(features)¶

Parameters:: 功能 – DockWidgetFeature 的组合

另请参阅

features()

属性 featuresᅟ 的设置器。

setFloating(floating)¶

Parameters:: floating – 布尔值

另请参阅

isFloating()

属性 floatingᅟ 的设置器。

setTitleBarWidget(widget)¶

Parameters:: widget – QWidget

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

设置一个任意的widget作为停靠窗口的标题栏。如果widget是None，则之前设置在停靠窗口上的任何自定义标题栏小部件将被移除，但不会被删除，并且将使用默认的标题栏。

如果设置了标题栏小部件，QDockWidget 在浮动时将不会使用本机窗口装饰。

以下是一些实现自定义标题栏的技巧：

未被标题栏小部件显式处理的鼠标事件必须通过调用QMouseEvent::ignore()来忽略。这些事件随后传播到QDockWidget父部件，父部件以通常的方式处理它们，当标题栏被拖动时移动，双击时停靠和取消停靠等。
当在QDockWidget上设置DockWidgetVerticalTitleBar时，标题栏小部件会相应地重新定位。在resizeEvent()中，标题栏应检查其应采用的朝向：
dockWidget = QDockWidget(parentWidget())
if dockWidget.features()  QDockWidget.DockWidgetVerticalTitleBar:
    # 我需要垂直
else:
    # 我需要水平
标题栏小部件必须具有有效的 sizeHint() 和 minimumSizeHint()。这些函数应考虑标题栏的当前方向。

无法从停靠小部件中移除标题栏。然而，可以通过将默认构造的QWidget设置为标题栏小部件来实现类似的效果。

如上所示使用 qobject_cast()，标题栏小部件可以完全访问其父级 QDockWidget。因此，它可以执行诸如停靠和隐藏等操作以响应用户操作。

另请参阅

titleBarWidget() DockWidgetVerticalTitleBar

setWidget(widget)¶

Parameters:: widget – QWidget

将停靠小部件的小部件设置为 widget。

如果添加 widget 时停靠小部件可见，您必须显式调用 show()。

请注意，在调用此函数之前，您必须添加widget的布局；否则，widget将不可见。

另请参阅

widget()

titleBarWidget()¶

Return type:: QWidget

返回设置在QDockWidget上的自定义标题栏小部件，如果未设置自定义标题栏，则返回None。

另请参阅

setTitleBarWidget()

toggleViewAction()¶

Return type:: QAction

返回一个可勾选的操作，可以添加到菜单和工具栏中，以便用户可以显示或关闭此停靠窗口部件。

操作的文本设置为停靠小部件的窗口标题。

注意

该操作不能用于以编程方式显示或隐藏停靠小部件。请使用 visible 属性来实现此功能。

另请参阅

windowTitle

topLevelChanged(topLevel)¶

Parameters:: topLevel – 布尔值

当floating属性发生变化时，会发出此信号。如果停靠部件现在处于浮动状态，则topLevel参数为true；否则为false。

另请参阅

isWindow()

属性 floatingᅟ 的通知信号。

visibilityChanged(visible)¶

Parameters:: visible – 布尔值

当停靠小部件变为可见（或不可见）时，会发出此信号。当小部件被隐藏或显示时，以及当它停靠在选项卡式停靠区域中并且其选项卡被选中或取消选中时，都会发生这种情况。

注意

信号可能与isVisible()不同。如果停靠窗口小部件被最小化或标签化，并且与非选中或非活动标签相关联，则可能会出现这种情况。

widget()¶

Return type:: QWidget

返回停靠小部件的小部件。如果小部件尚未设置，此函数返回零。

另请参阅

setWidget()

PySide6.QtWidgets.QDockWidget¶

概要¶

属性¶

方法¶

虚拟方法¶

信号¶

详细描述¶

外观¶