/****************************************************************************

**

** Copyright (C) 2009 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.

*/