/****************************************************************************
**
** Copyright (C) 2004-2007 Trolltech ASA. All rights reserved.
**
** This file is part of the documentation of the Qt Toolkit.
**
** This file may be used under the terms of the GNU General Public
** License version 2.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 GNU
** General Public Licensing requirements will be met:
** http://trolltech.com/products/qt/licenses/licensing/opensource/
**
** If you are unsure which license is appropriate for your use, please
** review the following information:
** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
** or contact the sales department at sales@trolltech.com.
**
** In addition, as a special exception, Trolltech gives you certain
** additional rights. These rights are described in the Trolltech GPL
** Exception version 1.0, which can be found at
** http://www.trolltech.com/products/qt/gplexception/ and in the file
** GPL_EXCEPTION.txt in this package.
**
** In addition, as a special exception, Trolltech, as the sole copyright
** holder for Qt Designer, grants users of the Qt/Eclipse Integration
** plug-in the right for the Qt/Eclipse Integration to link to
** functionality provided by Qt Designer and its related libraries.
**
** Trolltech reserves all rights not expressly granted herein.
**
** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
**
****************************************************************************/

/*!
    \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 and QGridLayout.

    \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.

    \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 and QGridLayout.

    We declare three private functions to simplify the class
    constructor: The \c createMenu(), \c createHorizontalGroupBox()
    and \c createGridGroupBox() 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, the \c createHorizontalGroupBox()
    function to create a group box containing four buttons with a
    horizontal layout, and the \c createGridGroupBox() function to
    create a group box containing several line edits and a small text
    editor, displayed in a grid layout.

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