--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/examples/basiclayouts.qdoc Thu Apr 08 14:19:33 2010 +0300
@@ -0,0 +1,204 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (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 Technology Preview License Agreement accompanying
+** this package.
+**
+** 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.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@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.
+*/