diff options
author | Axel Spoerl <axel.spoerl@qt.io> | 2023-12-04 09:18:44 +0100 |
---|---|---|
committer | Axel Spoerl <axel.spoerl@qt.io> | 2023-12-04 16:04:18 +0100 |
commit | 3591ea900b720ff48aace14cd81c8ec9d22b5c73 (patch) | |
tree | 3898ce65c33ff394f59dee8642d8b4f1cd61b7b4 | |
parent | 81b15adba2662142bd9917e29e38b8ca788e6a39 (diff) |
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 <volker.hilsheimer@qt.io>
-rw-r--r-- | src/widgets/widgets/qmainwindowlayout.cpp | 44 |
1 files changed, 34 insertions, 10 deletions
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<QDockWidgetGroupLayout> |