Revision control
++ // Copyright (C) 2016 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \example layouts/basiclayouts
++ \title Basic Layouts Example
++ \examplecategory {User Interface Components}
++ \brief Shows how to use the standard layout managers.
++
++ \e{Basic Layouts} shows how to use the standard layout managers that are
++ available in Qt: QBoxLayout, QGridLayout, and QFormLayout.
++
++ \image basiclayouts-example.png Screenshot of the Basic Layouts example
++
++ The QBoxLayout class lines up widgets horizontally or vertically.
++ QHBoxLayout and QVBoxLayout are convenience subclasses of QBoxLayout.
++ QGridLayout lays out widgets in cells by dividing the available space
++ into rows and columns. QFormLayout, on the other hand, sets its
++ children in a two-column form with labels in the left column and
++ input fields in the right column.
++
++ For more information, visit the \l{Layout Management} page.
++
++ \include examples-run.qdocinc
++
++ \section1 Dialog Class Definition
++
++ \snippet layouts/basiclayouts/dialog.h 0
++
++ The \c Dialog class inherits QDialog. It is a custom widget that
++ displays its child widgets using the geometry managers:
++ QHBoxLayout, QVBoxLayout, QGridLayout, and QFormLayout.
++
++ There are four private functions to simplify the class
++ constructor: the \c createMenu(), \c createHorizontalGroupBox(),
++ \c createGridGroupBox(), and \c createFormGroupBox() functions create
++ several widgets that the example uses to demonstrate how the layout
++ affects their appearances.
++
++ \section1 Dialog Class Implementation
++
++ \snippet layouts/basiclayouts/dialog.cpp 0
++
++ In the constructor, we first use the \c createMenu() function to
++ create and populate a menu bar and the \c createHorizontalGroupBox()
++ function to create a group box containing four buttons with a
++ horizontal layout. Next, we use the \c createGridGroupBox() function
++ to create a group box containing several line edits and a small text
++ editor which are displayed in a grid layout. Finally, we use the
++ \c createFormGroupBox() function to create a group box with
++ three labels and three input fields: a line edit, a combo box, and
++ a spin box.
++
++ \snippet layouts/basiclayouts/dialog.cpp 1
++
++ We also create a big text editor and a dialog button box. The
++ QDialogButtonBox class is a widget that presents buttons in a
++ layout that is appropriate to the current widget style. The
++ preferred buttons can be specified as arguments to the
++ constructor, using the QDialogButtonBox::StandardButtons enum.
++
++ Note that we don't have to specify a parent for the widgets when
++ we create them. The reason is that all the widgets we create here
++ will be added to a layout, and when we add a widget to a layout,
++ it is automatically reparented to the widget the layout is
++ installed on.
++
++ \snippet layouts/basiclayouts/dialog.cpp 2
++
++ The main layout is a QVBoxLayout object. QVBoxLayout is a
++ convenience class for a box layout with vertical orientation.
++
++ In general, the QBoxLayout class takes the space it gets (from its
++ parent layout or from the parent widget), divides it up into a
++ series of boxes, and makes each managed widget fill one box. If
++ the QBoxLayout's orientation is Qt::Horizontal the boxes are
++ placed in a row. If the orientation is Qt::Vertical, the boxes are
++ placed in a column. The corresponding convenience classes are
++ QHBoxLayout and QVBoxLayout, respectively.
++
++ \snippet layouts/basiclayouts/dialog.cpp 3
++
++ When we call the QLayout::setMenuBar() function, the layout places
++ the provided menu bar at the top of the parent widget, and outside
++ the widget's \l {QWidget::contentsRect()}{content margins}. All
++ child widgets are placed below the bottom edge of the menu bar.
++
++ \snippet layouts/basiclayouts/dialog.cpp 4
++
++ We use the QBoxLayout::addWidget() function to add the widgets to
++ the end of the layout. Each widget will get at least its minimum size
++ and at most its maximum size. It is possible to specify a stretch
++ factor in the \l {QBoxLayout::addWidget()}{addWidget()} function,
++ and any excess space is shared according to these stretch
++ factors. If not specified, a widget's stretch factor is 0.
++
++ \snippet layouts/basiclayouts/dialog.cpp 5
++
++ We install the main layout on the \c Dialog widget using the
++ QWidget::setLayout() function, and all of the layout's widgets are
++ automatically reparented to be children of the \c Dialog widget.
++
++ \snippet layouts/basiclayouts/dialog.cpp 6
++
++ In the private \c createMenu() function we create a menu bar, and
++ add a pull-down \uicontrol File menu containing an \uicontrol Exit option.
++
++ \snippet layouts/basiclayouts/dialog.cpp 7
++
++ When we create the horizontal group box, we use a QHBoxLayout as
++ the internal layout. We create the buttons we want to put in the
++ group box, add them to the layout and install the layout on the
++ group box.
++
++ \snippet layouts/basiclayouts/dialog.cpp 8
++
++ In the \c createGridGroupBox() function we use a QGridLayout which
++ lays out widgets in a grid. It takes the space made available to
++ it (by its parent layout or by the parent widget), divides it up
++ into rows and columns, and puts each widget it manages into the
++ correct cell.
++
++ \snippet layouts/basiclayouts/dialog.cpp 9
++
++ For each row in the grid we create a label and an associated line
++ edit, and add them to the layout. The QGridLayout::addWidget()
++ function differ from the corresponding function in QBoxLayout: It
++ needs the row and column specifying the grid cell to put the
++ widget in.
++
++ \snippet layouts/basiclayouts/dialog.cpp 10
++
++ QGridLayout::addWidget() can in addition take arguments
++ specifying the number of rows and columns the cell will be
++ spanning. In this example, we create a small editor which spans
++ three rows and one column.
++
++ For both the QBoxLayout::addWidget() and QGridLayout::addWidget()
++ functions it is also possible to add a last argument specifying
++ the widget's alignment. By default it fills the whole cell. But we
++ could, for example, align a widget with the right edge by
++ specifying the alignment to be Qt::AlignRight.
++
++ \snippet layouts/basiclayouts/dialog.cpp 11
++
++ Each column in a grid layout has a stretch factor. The stretch
++ factor is set using QGridLayout::setColumnStretch() and determines
++ how much of the available space the column will get over and above
++ its necessary minimum.
++
++ In this example, we set the stretch factors for columns 1 and 2.
++ The stretch factor is relative to the other columns in this grid;
++ columns with a higher stretch factor take more of the available
++ space. So column 2 in our grid layout will get more of the
++ available space than column 1, and column 0 will not grow at all
++ since its stretch factor is 0 (the default).
++
++ Columns and rows behave identically; there is an equivalent
++ stretch factor for rows, as well as a QGridLayout::setRowStretch()
++ function.
++
++ \snippet layouts/basiclayouts/dialog.cpp 12
++
++ In the \c createFormGroupBox() function, we use a QFormLayout
++ to neatly arrange objects into two columns - name and field.
++ There are three QLabel objects for names with three
++ corresponding input widgets as fields: a QLineEdit, a QComboBox
++ and a QSpinBox. Unlike QBoxLayout::addWidget() and
++ QGridLayout::addWidget(), we use QFormLayout::addRow() to add widgets
++ to the layout.
++ */