From 3591ea900b720ff48aace14cd81c8ec9d22b5c73 Mon Sep 17 00:00:00 2001 From: Axel Spoerl Date: Mon, 4 Dec 2023 09:18:44 +0100 Subject: Harden internal documentation of QDockWidgetGroupWindow QDockWidgetGroupWindow was documented by a few lines of code comments, omitting the most critical part of its design: It must not become able to acquire focus (i.e. be dragged or dropped) while having only one QDockWidget child. => replace legacy code comments by structured internal documentation. Pick-to: 6.6 6.5 Change-Id: I410ebf2e4c20c7479038417a4d8448dce8ab995f Reviewed-by: Volker Hilsheimer --- src/widgets/widgets/qmainwindowlayout.cpp | 44 ++++++++++++++++++++++++------- 1 file changed, 34 insertions(+), 10 deletions(-) (limited to 'src/widgets/widgets') diff --git a/src/widgets/widgets/qmainwindowlayout.cpp b/src/widgets/widgets/qmainwindowlayout.cpp index 9f26331ee9..52dec2efdf 100644 --- a/src/widgets/widgets/qmainwindowlayout.cpp +++ b/src/widgets/widgets/qmainwindowlayout.cpp @@ -168,16 +168,40 @@ static void dumpItemLists(const QMainWindowLayout *layout, const char *function, #endif // QT_CONFIG(dockwidget) && !defined(QT_NO_DEBUG) -/****************************************************************************** - ** QDockWidgetGroupWindow - */ -// QDockWidgetGroupWindow is the floating window containing several QDockWidgets floating together. -// (QMainWindow::GroupedDragging feature) -// QDockWidgetGroupLayout is the layout of that window and use a QDockAreaLayoutInfo to layout -// the QDockWidgets inside it. -// If there is only one QDockWidgets, or all QDockWidgets are tabbed together, it is equivalent -// of a floating QDockWidget (the title of the QDockWidget is the title of the window). But if there -// are nested QDockWidget, an additional title bar is there. + +/*! + \internal + QDockWidgetGroupWindow is a floating window, containing several QDockWidgets floating together. + This requires QMainWindow::GroupedDragging to be enabled. + QDockWidgets floating jointly in a QDockWidgetGroupWindow are considered to be docked. + Their \c isFloating property is \c false. + QDockWidget children of a QDockWidgetGroupWindow are either: + \list + \li tabbed (as long as Qt is compiled with the \c tabbar feature), or + \li arranged next to each other, equivalent to the default on a main window dock. + \endlist + + QDockWidgetGroupWindow uses QDockWidgetGroupLayout to lay out its QDockWidget children. + It stores layout information in a QDockAreaLayoutInfo, including temporary spacer items + and rubber bands. + + If its QDockWidget children are tabbed, the QDockWidgetGroupWindow shows the active QDockWidget's + title as its own window title. + + QDockWidgetGroupWindow is designed to hold more than one QDockWidget. + A QDockWidgetGroupWindow with only one QDockWidget child may occur only temporarily + \list + \li in its construction phase, or + \li during a hover: While QDockWidget A is hovered over B, B is converted into a QDockWidgetGroupWindow. + \endlist + + A QDockWidgetGroupWindow with only one QDockWidget child must never get focus, be dragged or dropped. + To enforce this restriction, QDockWidgetGrouWindow will remove itself after its second QDockWidget + child has been removed. It will make its last QDockWidget child a single, floating QDockWidget. + Eventually, the empty QDockWidgetGroupWindow will call deleteLater() on itself. +*/ + + #if QT_CONFIG(dockwidget) class QDockWidgetGroupLayout : public QLayout, public QMainWindowLayoutSeparatorHelper -- cgit v1.2.3