QLayout docs: explain better what the QWidget ctor arg does

Make it clear in the docs that an alternative to calling QWidget::setLayout()
is to pass the parent widget to the Q*BoxLayout constructor. This basically
just copies the relevant bits from the the docs of QWidget and Q*Layout.

Change-Id: Id196dcdf9a876d9141aa145f23a83c45f8cda5f8
Pick-to: 5.15 5.12
Reviewed-by: Richard Moe Gustavsen <richard.gustavsen@qt.io>

src/widgets/doc/snippets/layouts/layouts.cpp

@@ -67,7 +67,7 @@ int main(int argc, char *argv[])
 //! [2]
 
 //! [3]
-    QHBoxLayout *layout = new QHBoxLayout;
+    QHBoxLayout *layout = new QHBoxLayout(window);
 //! [3] //! [4]
     layout->addWidget(button1);
     layout->addWidget(button2);
@@ -75,7 +75,6 @@ int main(int argc, char *argv[])
     layout->addWidget(button4);
     layout->addWidget(button5);
 
-    window->setLayout(layout);
 //! [4]
     window->setWindowTitle("QHBoxLayout");
 //! [5]
@@ -96,7 +95,7 @@ int main(int argc, char *argv[])
 //! [8]
 
 //! [9]
-    QVBoxLayout *layout = new QVBoxLayout;
+    QVBoxLayout *layout = new QVBoxLayout(window);
 //! [9] //! [10]
     layout->addWidget(button1);
     layout->addWidget(button2);
@@ -104,7 +103,6 @@ int main(int argc, char *argv[])
     layout->addWidget(button4);
     layout->addWidget(button5);
 
-    window->setLayout(layout);
 //! [10]
     window->setWindowTitle("QVBoxLayout");
 //! [11]
@@ -125,7 +123,7 @@ int main(int argc, char *argv[])
 //! [14]
 
 //! [15]
-    QGridLayout *layout = new QGridLayout;
+    QGridLayout *layout = new QGridLayout(window);
 //! [15] //! [16]
     layout->addWidget(button1, 0, 0);
     layout->addWidget(button2, 0, 1);
@@ -133,7 +131,6 @@ int main(int argc, char *argv[])
     layout->addWidget(button4, 2, 0);
     layout->addWidget(button5, 2, 1);
 
-    window->setLayout(layout);
 //! [16]
     window->setWindowTitle("QGridLayout");
 //! [17]
@@ -156,14 +153,13 @@ int main(int argc, char *argv[])
     QLineEdit *lineEdit3 = new QLineEdit();
 //! [20]
 //! [21]
-    QFormLayout *layout = new QFormLayout;
+    QFormLayout *layout = new QFormLayout(window);
 //! [21]
 //! [22]
     layout->addRow(button1, lineEdit1);
     layout->addRow(button2, lineEdit2);
     layout->addRow(button3, lineEdit3);
 
-    window->setLayout(layout);
 //! [22]
     window->setWindowTitle("QFormLayout");
 //! [23]

src/widgets/kernel/qboxlayout.cpp

@@ -547,7 +547,11 @@ QLayoutItem* QBoxLayoutPrivate::replaceAt(int index, QLayoutItem *item)
     Constructs a new QBoxLayout with direction \a dir and parent widget \a
     parent.
 
-    \sa direction()
+    The layout is set directly as the top-level layout for \a parent.
+    There can be only one top-level layout for a widget. It is returned
+    by QWidget::layout().
+
+    \sa direction(), QWidget::setLayout()
 */
 QBoxLayout::QBoxLayout(Direction dir, QWidget *parent)
     : QLayout(*new QBoxLayoutPrivate, nullptr, parent)
@@ -1231,11 +1235,16 @@ QBoxLayout::Direction QBoxLayout::direction() const
     \snippet layouts/layouts.cpp 4
     \snippet layouts/layouts.cpp 5
 
-    First, we create the widgets we want in the layout. Then, we
+    First, we create the widgets we want to add to the layout. Then,
-    create the QHBoxLayout object and add the widgets into the
+    we create the QHBoxLayout object, setting \c window as parent by
-    layout. Finally, we call QWidget::setLayout() to install the
+    passing it in the constructor; next we add the widgets to the
-    QHBoxLayout object onto the widget. At that point, the widgets in
+    layout. \c window will be the parent of the widgets that are
-    the layout are reparented to have \c window as their parent.
+    added to the layout.
+
+    If you don't pass parent \c window in the constrcutor, you can
+    at a later point use QWidget::setLayout() to install the QHBoxLayout
+    object onto \c window. At that point, the widgets in the layout are
+    reparented to have \c window as their parent.
 
     \image qhboxlayout-with-5-children.png Horizontal box layout with five child widgets
 
@@ -1244,8 +1253,13 @@ QBoxLayout::Direction QBoxLayout::direction() const
 
 
 /*!
-    Constructs a new top-level horizontal box with
+    Constructs a new top-level horizontal box with parent \a parent.
-    parent \a parent.
+
+    The layout is set directly as the top-level layout for \a parent.
+    There can be only one top-level layout for a widget. It is returned
+    by QWidget::layout().
+
+    \sa QWidget::setLayout()
 */
 QHBoxLayout::QHBoxLayout(QWidget *parent)
     : QBoxLayout(LeftToRight, parent)
@@ -1294,11 +1308,16 @@ QHBoxLayout::~QHBoxLayout()
     \snippet layouts/layouts.cpp 10
     \snippet layouts/layouts.cpp 11
 
-    First, we create the widgets we want in the layout. Then, we
+    First, we create the widgets we want to add to the layout. Then,
-    create the QVBoxLayout object and add the widgets into the
+    we create the QVBoxLayout object, setting \c window as parent by
-    layout. Finally, we call QWidget::setLayout() to install the
+    passing it in the constructor; next we add the widgets to the
-    QVBoxLayout object onto the widget. At that point, the widgets in
+    layout. \c window will be the parent of the widgets that are
-    the layout are reparented to have \c window as their parent.
+    added to the layout.
+
+    If you don't pass parent \c window in the constrcutor, you can
+    at a later point use QWidget::setLayout() to install the QVBoxLayout
+    object onto \c window. At that point, the widgets in the layout are
+    reparented to have \c window as their parent.
 
     \image qvboxlayout-with-5-children.png Horizontal box layout with five child widgets
 
@@ -1306,8 +1325,13 @@ QHBoxLayout::~QHBoxLayout()
 */
 
 /*!
-    Constructs a new top-level vertical box with
+    Constructs a new top-level vertical box with parent \a parent.
-    parent \a parent.
+
+    The layout is set directly as the top-level layout for \a parent.
+    There can be only one top-level layout for a widget. It is returned
+    by QWidget::layout().
+
+    \sa QWidget::setLayout()
 */
 QVBoxLayout::QVBoxLayout(QWidget *parent)
     : QBoxLayout(TopToBottom, parent)

src/widgets/kernel/qformlayout.cpp

@@ -1189,6 +1189,10 @@ QLayoutItem* QFormLayoutPrivate::replaceAt(int index, QLayoutItem *newitem)
 /*!
     Constructs a new form layout with the given \a parent widget.
 
+    The layout is set directly as the top-level layout for \a parent.
+    There can be only one top-level layout for a widget. It is returned
+    by QWidget::layout().
+
     \sa QWidget::setLayout()
 */
 QFormLayout::QFormLayout(QWidget *parent)

src/widgets/kernel/qgridlayout.cpp

@@ -1072,6 +1072,12 @@ QRect QGridLayoutPrivate::cellRect(int row, int col) const
     Constructs a new QGridLayout with parent widget, \a parent.  The
     layout has one row and one column initially, and will expand when
     new items are inserted.
+
+    The layout is set directly as the top-level layout for \a parent.
+    There can be only one top-level layout for a widget. It is returned
+    by QWidget::layout().
+
+    \sa QWidget::setLayout()
 */
 QGridLayout::QGridLayout(QWidget *parent)
     : QLayout(*new QGridLayoutPrivate, nullptr, parent)