QDockWidget Class

成员函数文档

[explicit] QDockWidget::QDockWidget(QWidget *parent = nullptr, Qt::WindowFlags flags = Qt::WindowFlags())

创建一个 QDockWidget，其父窗口为parent ，窗口标志为flags 。该停靠控件将被放置在左侧的停靠区域中。

[explicit] QDockWidget::QDockWidget(const QString &title, QWidget *parent = nullptr, Qt::WindowFlags flags = Qt::WindowFlags())

创建一个父窗口为parent 、窗口标志为flags 的QDockWidget。该停靠控件将被放置在左侧停靠区域中。

窗口标题设置为title 。该标题在 QDockWidget 停靠和解停靠时均会使用，同时也会用于QMainWindow 提供的上下文菜单中。

另请参阅 setWindowTitle()。

[virtual noexcept] QDockWidget::~QDockWidget()

销毁dock控件。

[signal] void QDockWidget::allowedAreasChanged(Qt::DockWidgetAreas allowedAreas)

当allowedAreas 属性发生变化时，会触发此信号。allowedAreas 参数返回该属性的新值。

[override virtual protected] void QDockWidget::changeEvent(QEvent *event)

重写了：QWidget::changeEvent(QEvent *event)。

[override virtual protected] void QDockWidget::closeEvent(QCloseEvent *event)

重写了：QWidget::closeEvent(QCloseEvent *event)。

[signal] void QDockWidget::dockLocationChanged(Qt::DockWidgetArea area)

当停靠控件被移动到另一个停靠区area ，或被移动到其当前停靠区域内的其他位置时，会发出此信号。这种情况发生在通过编程方式移动停靠控件，或用户将其拖动到新位置时。

另请参阅 dockLocation() 和setDockLocation()。

[override virtual protected] bool QDockWidget::event(QEvent *event)

重写了：QWidget::event(QEvent *event)。

[signal] void QDockWidget::featuresChanged(QDockWidget::DockWidgetFeatures features)

当features 属性发生变化时，将触发此信号。features 参数返回该属性的新值。

[virtual protected] void QDockWidget::initStyleOption(QStyleOptionDockWidget *option) const

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

另请参阅 QStyleOption::initFrom()。

bool QDockWidget::isAreaAllowed(Qt::DockWidgetArea area) const

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

[override virtual protected] void QDockWidget::paintEvent(QPaintEvent *event)

重写：QWidget::paintEvent(QPaintEvent *event)。

[since 6.9] void QDockWidget::setDockLocation(Qt::DockWidgetArea area)

将此停靠控件分配给area 。如果当前停靠在其他位置，它将移动到area 。如果处于浮动状态或属于浮动标签页，则下次调用setFloating(false)时，它将停靠在area 。

该函数在 Qt 6.9 中引入。

另请参阅 dockLocation() 和dockLocationChanged()。

void QDockWidget::setTitleBarWidget(QWidget *widget)

将任意widget 设置为停靠控件的标题栏。如果widget 的值为nullptr ，则之前在停靠控件上设置的任何自定义标题栏控件将被移除（但不会被删除），并改用默认标题栏。

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

以下是实现自定义标题栏的一些提示：

• 对于未被标题栏控件显式处理的鼠标事件，必须通过调用 `QMouseEvent::ignore()` 将其忽略。这些事件随后会传播到父控件 `QDockWidget `，由其以常规方式进行处理，例如在拖动标题栏时移动窗口，双击时进行停靠和取消停靠等。
• 当在 `QDockWidget` 上设置 `DockWidgetVerticalTitleBar ` 时，标题栏控件将相应地重新定位。在 `resizeEvent()` 中，标题栏应检查其应采用何种方向：

  QDockWidget *dockWidget = qobject_cast<QDockWidget*>(parentWidget());
  if (dockWidget->features() & QDockWidget::DockWidgetVerticalTitleBar) {
      // I need to be vertical
  } else {
      // I need to be horizontal
  }

• 标题栏控件必须具有有效的QWidget::sizeHint() 和QWidget::minimumSizeHint() 方法。这些方法应考虑标题栏的当前方向。
• 无法从停靠控件中移除标题栏。不过，可以通过将默认构造的QWidget 设置为标题栏控件来实现类似效果。

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

另请参阅 titleBarWidget() 和DockWidgetVerticalTitleBar 。

void QDockWidget::setWidget(QWidget *widget)

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

如果在添加widget 时停靠控件处于可见状态，则必须显式地调用show()。

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

另请参阅 widget()。

QWidget *QDockWidget::titleBarWidget() const

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

另请参阅 setTitleBarWidget()。

QAction *QDockWidget::toggleViewAction() const

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

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

QAction 对象由QDockWidget 拥有。当QDockWidget 被销毁时，该对象将被自动删除。

另请参阅 QAction::text 和QWidget::windowTitle 。

[signal] void QDockWidget::topLevelChanged(bool topLevel)

当floating 属性发生变化时，将触发此信号。若停靠控件当前处于浮动状态，则topLevel 参数为true；否则为false。

另请参阅 isWindow()。

[signal] void QDockWidget::visibilityChanged(bool visible)

当停靠控件变为visible （或不可见）时，会触发此信号。这种情况发生在控件被隐藏或显示时，以及当控件停靠在带标签的停靠区域中，且其标签被选中或取消选中时。

QWidget *QDockWidget::widget() const

返回停靠控件对应的控件。如果尚未设置该控件，则该函数返回零。

另请参阅 setWidget()。