diff options
Diffstat (limited to 'examples/widgets/doc/basiclayouts.qdoc')
| -rw-r--r-- | examples/widgets/doc/basiclayouts.qdoc | 190 |
1 files changed, 190 insertions, 0 deletions
diff --git a/examples/widgets/doc/basiclayouts.qdoc b/examples/widgets/doc/basiclayouts.qdoc new file mode 100644 index 0000000000..a0f083ba58 --- /dev/null +++ b/examples/widgets/doc/basiclayouts.qdoc @@ -0,0 +1,190 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example layouts/basiclayouts + \title Basic Layouts Example + + The Basic Layouts example 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, lays out its + children in a two-column form with labels in the left column and + input fields in the right column. + + \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. + + We declare 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 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. +*/ |