doc/src/examples/basiclayouts.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2015 The Qt Company Ltd.
   4 ** Contact: http://www.qt.io/licensing/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and The Qt Company. For licensing terms
  14 ** and conditions see http://www.qt.io/terms-conditions. For further
  15 ** information use the contact form at http://www.qt.io/contact-us.
  16 **
  17 ** GNU Free Documentation License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Free
  19 ** Documentation License version 1.3 as published by the Free Software
  20 ** Foundation and appearing in the file included in the packaging of
  21 ** this file.  Please review the following information to ensure
  22 ** the GNU Free Documentation License version 1.3 requirements
  23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \example layouts/basiclayouts
  30     \title Basic Layouts Example
  31
  32     \brief The Basic Layouts example shows how to use the standard layout
  33     managers that are available in Qt: QBoxLayout, QGridLayout and
  34     QFormLayout.
  35
  36     \image basiclayouts-example.png Screenshot of the Basic Layouts example
  37
  38     The QBoxLayout class lines up widgets horizontally or vertically.
  39     QHBoxLayout and QVBoxLayout are convenience subclasses of QBoxLayout.
  40     QGridLayout lays out widgets in cells by dividing the available space
  41     into rows and columns. QFormLayout, on the other hand, lays out its
  42     children in a two-column form with labels in the left column and
  43     input fields in the right column.
  44
  45     \section1 Dialog Class Definition
  46
  47     \snippet examples/layouts/basiclayouts/dialog.h 0
  48
  49     The \c Dialog class inherits QDialog. It is a custom widget that
  50     displays its child widgets using the geometry managers:
  51     QHBoxLayout, QVBoxLayout, QGridLayout and QFormLayout.
  52
  53     We declare four private functions to simplify the class
  54     constructor: The \c createMenu(), \c createHorizontalGroupBox(),
  55     \c createGridGroupBox() and \c createFormGroupBox() functions create
  56     several widgets that the example uses to demonstrate how the layout
  57     affects their appearances.
  58
  59     \section1 Dialog Class Implementation
  60
  61     \snippet examples/layouts/basiclayouts/dialog.cpp 0
  62
  63     In the constructor, we first use the \c createMenu() function to
  64     create and populate a menu bar and the \c createHorizontalGroupBox()
  65     function to create a group box containing four buttons with a
  66     horizontal layout. Next we use the \c createGridGroupBox() function
  67     to create a group box containing several line edits and a small text
  68     editor which are displayed in a grid layout. Finally, we use the
  69     \c createFormGroupBox() function to create a group box with
  70     three labels and three input fields: a line edit, a combo box and
  71     a spin box.
  72
  73     \snippet examples/layouts/basiclayouts/dialog.cpp 1
  74
  75     We also create a big text editor and a dialog button box. The
  76     QDialogButtonBox class is a widget that presents buttons in a
  77     layout that is appropriate to the current widget style. The
  78     preferred buttons can be specified as arguments to the
  79     constructor, using the QDialogButtonBox::StandardButtons enum.
  80
  81     Note that we don't have to specify a parent for the widgets when
  82     we create them. The reason is that all the widgets we create here
  83     will be added to a layout, and when we add a widget to a layout,
  84     it is automatically reparented to the widget the layout is
  85     installed on.
  86
  87     \snippet examples/layouts/basiclayouts/dialog.cpp 2
  88
  89     The main layout is a QVBoxLayout object. QVBoxLayout is a
  90     convenience class for a box layout with vertical orientation.
  91
  92     In general, the QBoxLayout class takes the space it gets (from its
  93     parent layout or from the parent widget), divides it up into a
  94     series of boxes, and makes each managed widget fill one box.  If
  95     the QBoxLayout's orientation is Qt::Horizontal the boxes are
  96     placed in a row. If the orientation is Qt::Vertical, the boxes are
  97     placed in a column.  The corresponding convenience classes are
  98     QHBoxLayout and QVBoxLayout, respectively.
  99
 100     \snippet examples/layouts/basiclayouts/dialog.cpp 3
 101
 102     When we call the QLayout::setMenuBar() function, the layout places
 103     the provided menu bar at the top of the parent widget, and outside
 104     the widget's \l {QWidget::contentsRect()}{content margins}. All
 105     child widgets are placed below the bottom edge of the menu bar.
 106
 107     \snippet examples/layouts/basiclayouts/dialog.cpp 4
 108
 109     We use the QBoxLayout::addWidget() function to add the widgets to
 110     the end of layout. Each widget will get at least its minimum size
 111     and at most its maximum size. It is possible to specify a stretch
 112     factor in the \l {QBoxLayout::addWidget()}{addWidget()} function,
 113     and any excess space is shared according to these stretch
 114     factors. If not specified, a widget's stretch factor is 0.
 115
 116     \snippet examples/layouts/basiclayouts/dialog.cpp 5
 117
 118     We install the main layout on the \c Dialog widget using the
 119     QWidget::setLayout() function, and all of the layout's widgets are
 120     automatically reparented to be children of the \c Dialog widget.
 121
 122     \snippet examples/layouts/basiclayouts/dialog.cpp 6
 123
 124     In the private \c createMenu() function we create a menu bar, and
 125     add a pull-down \gui File menu containing an \gui Exit option.
 126
 127     \snippet examples/layouts/basiclayouts/dialog.cpp 7
 128
 129     When we create the horizontal group box, we use a QHBoxLayout as
 130     the internal layout. We create the buttons we want to put in the
 131     group box, add them to the layout and install the layout on the
 132     group box.
 133
 134     \snippet examples/layouts/basiclayouts/dialog.cpp 8
 135
 136     In the \c createGridGroupBox() function we use a QGridLayout which
 137     lays out widgets in a grid. It takes the space made available to
 138     it (by its parent layout or by the parent widget), divides it up
 139     into rows and columns, and puts each widget it manages into the
 140     correct cell.
 141
 142     \snippet examples/layouts/basiclayouts/dialog.cpp 9
 143
 144     For each row in the grid we create a label and an associated line
 145     edit, and add them to the layout. The QGridLayout::addWidget()
 146     function differ from the corresponding function in QBoxLayout: It
 147     needs the row and column specifying the grid cell to put the
 148     widget in.
 149
 150     \snippet examples/layouts/basiclayouts/dialog.cpp 10
 151
 152     QGridLayout::addWidget() can in addition take arguments
 153     specifying the number of rows and columns the cell will be
 154     spanning. In this example, we create a small editor which spans
 155     three rows and one column.
 156
 157     For both the QBoxLayout::addWidget() and QGridLayout::addWidget()
 158     functions it is also possible to add a last argument specifying
 159     the widget's alignment. By default it fills the whole cell. But we
 160     could, for example, align a widget with the right edge by
 161     specifying the alignment to be Qt::AlignRight.
 162
 163     \snippet examples/layouts/basiclayouts/dialog.cpp 11
 164
 165     Each column in a grid layout has a stretch factor. The stretch
 166     factor is set using QGridLayout::setColumnStretch() and determines
 167     how much of the available space the column will get over and above
 168     its necessary minimum.
 169
 170     In this example, we set the stretch factors for columns 1 and 2.
 171     The stretch factor is relative to the other columns in this grid;
 172     columns with a higher stretch factor take more of the available
 173     space. So column 2 in our grid layout will get more of the
 174     available space than column 1, and column 0 will not grow at all
 175     since its stretch factor is 0 (the default).
 176
 177     Columns and rows behave identically; there is an equivalent
 178     stretch factor for rows, as well as a QGridLayout::setRowStretch()
 179     function.
 180
 181     \snippet examples/layouts/basiclayouts/dialog.cpp 12
 182
 183     In the \c createFormGroupBox() function, we use a QFormLayout
 184     to neatly arrange objects into two columns - name and field.
 185     There are three QLabel objects for names with three
 186     corresponding input widgets as fields: a QLineEdit, a QComboBox
 187     and a QSpinBox. Unlike QBoxLayout::addWidget() and
 188     QGridLayout::addWidget(), we use QFormLayout::addRow() to add widgets
 189     to the layout.
 190 */