1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
/****************************************************************************
**
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia. For licensing terms and
** conditions see http://qt.digia.com/licensing. For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\example layouts/basiclayouts
\title Basic Layouts Example
\brief 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 create 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.
*/
|
