Long live Qt 4.5!

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.
+*/