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