source: trunk/doc/src/examples/flowlayout.qdoc@ 605

Last change on this file since 605 was 561, checked in by Dmitry A. Kuminov, 16 years ago

trunk: Merged in qt 4.6.1 sources.
File size: 6.8 KB
Line 
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** 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
13** Software or, alternatively, in accordance with the terms contained in
14** a written agreement between you and Nokia.
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** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you have questions regarding the use of this file, please contact
37** Nokia at qt-info@nokia.com.
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42/*!
43 \example layouts/flowlayout
44 \title Flow Layout Example
45
46 The Flow Layout example demonstrates a custom layout that arranges child
47 widgets from left to right and top to bottom in a top-level widget.
48
49 \image flowlayout-example.png Screenshot of the Flow Layout example
50
51 The items are first laid out horizontally and then vertically when each line
52 in the layout runs out of space.
53
54 The Flowlayout class mainly uses QLayout and QWidgetItem, while the
55 Window uses QWidget and QLabel. We will only document the definition
56 and implementation of \c FlowLayout below.
57
58 \section1 FlowLayout Class Definition
59
60 The \c FlowLayout class inherits QLayout. It is a custom layout class
61 that arranges its child widgets horizontally and vertically.
62
63 \snippet examples/layouts/flowlayout/flowlayout.h 0
64
65 We reimplement functions inherited from QLayout. These functions add items to
66 the layout and handle their orientation and geometry.
67
68 We also declare two private methods, \c doLayout() and \c smartSpacing().
69 \c doLayout() lays out the layout items, while the \c
70 smartSpacing() function calculates the spacing between them.
71
72 \section1 FlowLayout Class Implementation
73
74 We start off by looking at the constructor:
75
76 \snippet examples/layouts/flowlayout/flowlayout.cpp 1
77
78 In the constructor we call \c setContentsMargins() to set the left, top,
79 right and bottom margin. By default, QLayout uses values provided by
80 the current style (see QStyle::PixelMetric).
81
82 \snippet examples/layouts/flowlayout/flowlayout.cpp 2
83
84 In this example we reimplement \c addItem(), which is a pure virtual
85 function. When using \c addItem() the ownership of the layout items is
86 transferred to the layout, and it is therefore the layout's
87 responsibility to delete them.
88
89 \snippet examples/layouts/flowlayout/flowlayout.cpp 3
90
91 \c addItem() is implemented to add items to the layout.
92
93 \snippet examples/layouts/flowlayout/flowlayout.cpp 4
94
95 We implement \c horizontalSpacing() and \c verticalSpacing() to get
96 hold of the spacing between the widgets inside the layout. If the value
97 is less than or equal to 0, this value will be used. If not,
98 \c smartSpacing() will be called to calculate the spacing.
99
100 \snippet examples/layouts/flowlayout/flowlayout.cpp 5
101
102 We then implement \c count() to return the number of items in the
103 layout. To navigate the list of items we use \c itemAt() and
104 takeAt() to remove and return items from the list. If an item is
105 removed, the remaining items will be renumbered. All three
106 functions are pure virtual functions from QLayout.
107
108 \snippet examples/layouts/flowlayout/flowlayout.cpp 6
109
110 \c expandingDirections() returns the \l{Qt::Orientation}s in which the
111 layout can make use of more space than its \c sizeHint().
112
113 \snippet examples/layouts/flowlayout/flowlayout.cpp 7
114
115 To adjust to widgets of which height is dependent on width, we implement \c
116 heightForWidth(). The function \c hasHeightForWidth() is used to test for this
117 dependency, and \c heightForWidth() passes the width on to \c doLayout() which
118 in turn uses the width as an argument for the layout rect, i.e., the bounds in
119 which the items are laid out. This rect does not include the layout margin().
120
121 \snippet examples/layouts/flowlayout/flowlayout.cpp 8
122
123 \c setGeometry() is normally used to do the actual layout, i.e., calculate
124 the geometry of the layout's items. In this example, it calls \c doLayout()
125 and passes the layout rect.
126
127 \c sizeHint() returns the preferred size of the layout and \c minimumSize()
128 returns the minimum size of the layout.
129
130 \snippet examples/layouts/flowlayout/flowlayout.cpp 9
131
132 \c doLayout() handles the layout if \c horizontalSpacing() or \c
133 verticalSpacing() don't return the default value. It uses
134 \c getContentsMargins() to calculate the area available to the
135 layout items.
136
137 \snippet examples/layouts/flowlayout/flowlayout.cpp 10
138
139 It then sets the proper amount of spacing for each widget in the
140 layout, based on the current style.
141
142 \snippet examples/layouts/flowlayout/flowlayout.cpp 11
143
144 The position of each item in the layout is then calculated by
145 adding the items width and the line height to the initial x and y
146 coordinates. This in turn lets us find out whether the next item
147 will fit on the current line or if it must be moved down to the next.
148 We also find the height of the current line based on the widgets height.
149
150 \snippet examples/layouts/flowlayout/flowlayout.cpp 12
151
152 \c smartSpacing() is designed to get the default spacing for either
153 the top-level layouts or the sublayouts. The default spacing for
154 top-level layouts, when the parent is a QWidget, will be determined
155 by querying the style. The default spacing for sublayouts, when
156 the parent is a QLayout, will be determined by querying the spacing
157 of the parent layout.
158
159*/
Note: See TracBrowser for help on using the repository browser.