| /**************************************************************************** |
| ** |
| ** Copyright (C) 2016 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** This file is part of the documentation of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:FDL$ |
| ** Commercial License Usage |
| ** Licensees holding valid commercial Qt licenses may use this file in |
| ** accordance with the commercial license agreement provided with the |
| ** Software or, alternatively, in accordance with the terms contained in |
| ** a written agreement between you and The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/contact-us. |
| ** |
| ** GNU Free Documentation License Usage |
| ** Alternatively, this file may be used under the terms of the GNU Free |
| ** Documentation License version 1.3 as published by the Free Software |
| ** Foundation and appearing in the file included in the packaging of |
| ** this file. Please review the following information to ensure |
| ** the GNU Free Documentation License version 1.3 requirements |
| ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \example layouts/basiclayouts |
| \title Basic Layouts Example |
| \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. |
| */ |