The Problem: QMainWindow Freezes Size Updates After Floating a Dock

When working with dynamic docking systems in PySide6 (or PyQt6/PyQt5), you might encounter a frustrating layout bug: dynamically adding multiple QDockWidget instances works fine initially, but as soon as you detach one dock and make it float, the QMainWindow stops resizing its central widget and remaining docked widgets.

The central widget appears locked in place until you re-dock the floating window. This occurs because Qt's internal dock layout manager (QMainWindowLayout) can get desynchronized when docks are dynamically created without proper layout hints, unique object identifiers, or explicit nested dock configuration.

Why Does This Happen?

There are a few underlying reasons for this behavior in Qt:

  • Missing Unique Object Names: Qt relies on setObjectName() to manage and restore dock states. Without unique names, Qt can confuse geometry states between multiple docks sharing the same default object name.
  • Dock Nesting & Options: By default, some dock configurations don't handle dynamic splitting and undocking gracefully unless nested docks (QMainWindow.AllowNestedDocks) are explicitly allowed.
  • Unrefreshed Layout Geometry: When a dock is detached to the desktop, the main window layout does not always automatically invalidate its internal separator calculations.

The Solution

To resolve the issue and ensure your QMainWindow resizes smoothly when docks are floated, apply the following adjustments:

  1. Enable nested docks using self.setDockOptions().
  2. Assign a unique objectName to each dynamically created QDockWidget.
  3. Connect the topLevelChanged signal of the dock widget to invalidate and refresh the main window layout.

Updated & Working PySide6 Example

import sys
from PySide6.QtCore import Qt
from PySide6.QtWidgets import (
    QApplication,
    QDockWidget,
    QLabel,
    QMainWindow,
    QPushButton,
    QSizePolicy,
)


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.dock_count = 0

        # 1. Configure Dock Options to allow flexible layouts
        self.setDockOptions(
            QMainWindow.DockOption.AnimatedDocks
            | QMainWindow.DockOption.AllowNestedDocks
            | QMainWindow.DockOption.AllowTabbedDocks
        )

        # 2. Central Widget setup
        btn = QPushButton("Create Dock")
        btn.setSizePolicy(QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Expanding)
        btn.clicked.connect(self.create_dock)
        self.setCentralWidget(btn)

    def create_dock(self) -> None:
        self.dock_count += 1
        dock_name = f"Dock {self.dock_count}"
        
        dock = QDockWidget(dock_name, self)
        # 3. Give every dock a unique objectName
        dock.setObjectName(f"dynamic_dock_{self.dock_count}")
        
        dock.setWidget(QLabel(f"Content for {dock_name}"))
        
        # 4. Trigger layout activation whenever a dock floats or docks
        dock.topLevelChanged.connect(self.on_dock_toplevel_changed)
        
        self.addDockWidget(Qt.DockWidgetArea.BottomDockWidgetArea, dock)

    def on_dock_toplevel_changed(self, is_floating: bool) -> None:
        # Force QMainWindow to recalculate layout geometries
        if self.layout():
            self.layout().activate()
        self.updateGeometry()


if __name__ == "__main__":
    app = QApplication(sys.argv)
    window = MainWindow()
    window.resize(600, 400)
    window.show()
    sys.exit(app.exec())

Key Takeaways

  • Always set AllowNestedDocks: Calling setDockOptions() ensures that Qt manages dynamic multi-dock splitting cleanly without breaking the layout separators.
  • Hook into topLevelChanged: This signal fires whenever a dock is dragged out to float or attached back into the main window, allowing you to force a layout recalculation using self.layout().activate().
  • Assign unique object names: Dynamic Qt widgets with dockable or stateful properties should always have distinct setObjectName() values.