1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the documentation of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43     \example layouts/basiclayouts

    44     \title Basic Layouts Example

    45 

    46     The Basic Layouts example shows how to use the standard layout

    47     managers that are available in Qt: QBoxLayout, QGridLayout and

    48     QFormLayout.

    49 

    50     \image basiclayouts-example.png Screenshot of the Basic Layouts example

    51 

    52     The QBoxLayout class lines up widgets horizontally or vertically.

    53     QHBoxLayout and QVBoxLayout are convenience subclasses of QBoxLayout.

    54     QGridLayout lays out widgets in cells by dividing the available space

    55     into rows and columns. QFormLayout, on the other hand, lays out its

    56     children in a two-column form with labels in the left column and

    57     input fields in the right column.

    58 

    59     \section1 Dialog Class Definition

    60 

    61     \snippet examples/layouts/basiclayouts/dialog.h 0

    62 

    63     The \c Dialog class inherits QDialog. It is a custom widget that

    64     displays its child widgets using the geometry managers:

    65     QHBoxLayout, QVBoxLayout, QGridLayout and QFormLayout.

    66 

    67     We declare four private functions to simplify the class

    68     constructor: The \c createMenu(), \c createHorizontalGroupBox(),

    69     \c createGridGroupBox() and \c createFormGroupBox() functions create

    70     several widgets that the example uses to demonstrate how the layout

    71     affects their appearances.

    72 

    73     \section1 Dialog Class Implementation

    74 

    75     \snippet examples/layouts/basiclayouts/dialog.cpp 0

    76 

    77     In the constructor, we first use the \c createMenu() function to

    78     create and populate a menu bar and the \c createHorizontalGroupBox()

    79     function to create a group box containing four buttons with a

    80     horizontal layout. Next we use the \c createGridGroupBox() function

    81     to create a group box containing several line edits and a small text

    82     editor which are displayed in a grid layout. Finally, we use the

    83     \c createFormGroupBox() function to createa a group box with

    84     three labels and three input fields: a line edit, a combo box and

    85     a spin box.

    86 

    87     \snippet examples/layouts/basiclayouts/dialog.cpp 1

    88 

    89     We also create a big text editor and a dialog button box. The

    90     QDialogButtonBox class is a widget that presents buttons in a

    91     layout that is appropriate to the current widget style. The

    92     preferred buttons can be specified as arguments to the

    93     constructor, using the QDialogButtonBox::StandardButtons enum.

    94 

    95     Note that we don't have to specify a parent for the widgets when

    96     we create them. The reason is that all the widgets we create here

    97     will be added to a layout, and when we add a widget to a layout,

    98     it is automatically reparented to the widget the layout is

    99     installed on.

   100 

   101     \snippet examples/layouts/basiclayouts/dialog.cpp 2

   102 

   103     The main layout is a QVBoxLayout object. QVBoxLayout is a

   104     convenience class for a box layout with vertical orientation.

   105 

   106     In general, the QBoxLayout class takes the space it gets (from its

   107     parent layout or from the parent widget), divides it up into a

   108     series of boxes, and makes each managed widget fill one box.  If

   109     the QBoxLayout's orientation is Qt::Horizontal the boxes are

   110     placed in a row. If the orientation is Qt::Vertical, the boxes are

   111     placed in a column.  The corresponding convenience classes are

   112     QHBoxLayout and QVBoxLayout, respectively.

   113 

   114     \snippet examples/layouts/basiclayouts/dialog.cpp 3

   115 

   116     When we call the QLayout::setMenuBar() function, the layout places

   117     the provided menu bar at the top of the parent widget, and outside

   118     the widget's \l {QWidget::contentsRect()}{content margins}. All

   119     child widgets are placed below the bottom edge of the menu bar.

   120 

   121     \snippet examples/layouts/basiclayouts/dialog.cpp 4

   122 

   123     We use the QBoxLayout::addWidget() function to add the widgets to

   124     the end of layout. Each widget will get at least its minimum size

   125     and at most its maximum size. It is possible to specify a stretch

   126     factor in the \l {QBoxLayout::addWidget()}{addWidget()} function,

   127     and any excess space is shared according to these stretch

   128     factors. If not specified, a widget's stretch factor is 0.

   129 

   130     \snippet examples/layouts/basiclayouts/dialog.cpp 5

   131 

   132     We install the main layout on the \c Dialog widget using the

   133     QWidget::setLayout() function, and all of the layout's widgets are

   134     automatically reparented to be children of the \c Dialog widget.

   135 

   136     \snippet examples/layouts/basiclayouts/dialog.cpp 6

   137 

   138     In the private \c createMenu() function we create a menu bar, and

   139     add a pull-down \gui File menu containing an \gui Exit option.

   140 

   141     \snippet examples/layouts/basiclayouts/dialog.cpp 7

   142 

   143     When we create the horizontal group box, we use a QHBoxLayout as

   144     the internal layout. We create the buttons we want to put in the

   145     group box, add them to the layout and install the layout on the

   146     group box.

   147 

   148     \snippet examples/layouts/basiclayouts/dialog.cpp 8

   149 

   150     In the \c createGridGroupBox() function we use a QGridLayout which

   151     lays out widgets in a grid. It takes the space made available to

   152     it (by its parent layout or by the parent widget), divides it up

   153     into rows and columns, and puts each widget it manages into the

   154     correct cell.

   155 

   156     \snippet examples/layouts/basiclayouts/dialog.cpp 9

   157 

   158     For each row in the grid we create a label and an associated line

   159     edit, and add them to the layout. The QGridLayout::addWidget()

   160     function differ from the corresponding function in QBoxLayout: It

   161     needs the row and column specifying the grid cell to put the

   162     widget in.

   163 

   164     \snippet examples/layouts/basiclayouts/dialog.cpp 10

   165 

   166     QGridLayout::addWidget() can in addition take arguments

   167     specifying the number of rows and columns the cell will be

   168     spanning. In this example, we create a small editor which spans

   169     three rows and one column.

   170 

   171     For both the QBoxLayout::addWidget() and QGridLayout::addWidget()

   172     functions it is also possible to add a last argument specifying

   173     the widget's alignment. By default it fills the whole cell. But we

   174     could, for example, align a widget with the right edge by

   175     specifying the alignment to be Qt::AlignRight.

   176 

   177     \snippet examples/layouts/basiclayouts/dialog.cpp 11

   178 

   179     Each column in a grid layout has a stretch factor. The stretch

   180     factor is set using QGridLayout::setColumnStretch() and determines

   181     how much of the available space the column will get over and above

   182     its necessary minimum.

   183 

   184     In this example, we set the stretch factors for columns 1 and 2.

   185     The stretch factor is relative to the other columns in this grid;

   186     columns with a higher stretch factor take more of the available

   187     space. So column 2 in our grid layout will get more of the

   188     available space than column 1, and column 0 will not grow at all

   189     since its stretch factor is 0 (the default).

   190 

   191     Columns and rows behave identically; there is an equivalent

   192     stretch factor for rows, as well as a QGridLayout::setRowStretch()

   193     function.

   194 

   195     \snippet examples/layouts/basiclayouts/dialog.cpp 12

   196 

   197     In the \c createFormGroupBox() function, we use a QFormLayout

   198     to neatly arrange objects into two columns - name and field.

   199     There are three QLabel objects for names with three

   200     corresponding input widgets as fields: a QLineEdit, a QComboBox

   201     and a QSpinBox. Unlike QBoxLayout::addWidget() and

   202     QGridLayout::addWidget(), we use QFormLayout::addRow() to add widgets

   203     to the layout.

   204 */