source: trunk/doc/src/examples/basiclayouts.qdoc

Last change on this file was 846, checked in by Dmitry A. Kuminov, 14 years ago

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.
File size: 8.3 KB
RevLine 
[2]1/****************************************************************************
2**
[846]3** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
[561]4** All rights reserved.
5** Contact: Nokia Corporation (qt-info@nokia.com)
[2]6**
7** This file is part of the documentation of the Qt Toolkit.
8**
[846]9** $QT_BEGIN_LICENSE:FDL$
[2]10** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
[846]13** Software or, alternatively, in accordance with the terms contained in a
14** written agreement between you and Nokia.
[2]15**
[846]16** GNU Free Documentation License
17** Alternatively, this file may be used under the terms of the GNU Free
18** Documentation License version 1.3 as published by the Free Software
19** Foundation and appearing in the file included in the packaging of this
20** file.
[2]21**
[561]22** If you have questions regarding the use of this file, please contact
23** Nokia at qt-info@nokia.com.
[2]24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29 \example layouts/basiclayouts
30 \title Basic Layouts Example
31
32 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
[846]69 \c createFormGroupBox() function to create a group box with
[2]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*/
Note: See TracBrowser for help on using the repository browser.