diff options
Diffstat (limited to 'doc/src/examples/basiclayouts.qdoc')
| -rw-r--r-- | doc/src/examples/basiclayouts.qdoc | 204 |
1 files changed, 204 insertions, 0 deletions
diff --git a/doc/src/examples/basiclayouts.qdoc b/doc/src/examples/basiclayouts.qdoc new file mode 100644 index 0000000..0d64b1f --- /dev/null +++ b/doc/src/examples/basiclayouts.qdoc @@ -0,0 +1,204 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $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 examples/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 examples/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 createa a group box with + three labels and three input fields: a line edit, a combo box and + a spin box. + + \snippet examples/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 examples/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 examples/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 examples/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 examples/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 examples/layouts/basiclayouts/dialog.cpp 6 + + In the private \c createMenu() function we create a menu bar, and + add a pull-down \gui File menu containing an \gui Exit option. + + \snippet examples/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 examples/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 examples/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 examples/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 examples/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 examples/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. +*/ |