source: trunk/doc/src/examples/basicgraphicslayouts.qdoc@ 1168

Last change on this file since 1168 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.8 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 graphicsview/basicgraphicslayouts
30 \title Basic Graphics Layouts Example
31
32 The Basic Graphics Layouts example shows how to use the layout classes
33 in QGraphicsView: QGraphicsLinearLayout and QGraphicsGridLayout.
34 In addition to that it shows how to write your own custom layout item.
35
36 \image basicgraphicslayouts-example.png Screenshot of the Basic Layouts Example
37
38 \section1 Window Class Definition
39
40 The \c Window class is a subclass of QGraphicsWidget. It has a
41 constructor with a QGraphicsWidget \a parent as its parameter.
42
43 \snippet examples/graphicsview/basicgraphicslayouts/window.h 0
44
45 \section1 Window Class Implementation
46
47 The constructor of \c Window instantiates a QGraphicsLinearLayout object,
48 \c windowLayout, with vertical orientation. We instantiate another
49 QGraphicsLinearLayout object, \c linear, whose parent is \c windowLayout.
50 Next, we create a \c LayoutItem object, \c item and add it to \c linear
51 with the \l{QGraphicsLinearLayout::}{addItem()} function. We also provide
52 \c item with a \l{QGraphicsLinearLayout::setStretchFactor()}
53 {stretchFactor}.
54
55 \snippet examples/graphicsview/basicgraphicslayouts/window.cpp 0
56
57 We repeat the process:
58
59 \list
60 \o create a new \c LayoutItem,
61 \o add the item \c linear, and
62 \o provide a stretch factor.
63 \endlist
64
65 \snippet examples/graphicsview/basicgraphicslayouts/window.cpp 1
66
67 We then add \c linear to \c windowLayout, nesting two
68 QGraphicsLinearLayout objects. Apart from the QGraphicsLinearLayout, we
69 also use a QGraphicsGridLayout object, \c grid, which is a 4x3 grid with
70 some cells spanning to other rows.
71
72 We create seven \c LayoutItem objects and place them into \c grid with
73 the \l{QGraphicsGridLayout::}{addItem()} function as shown in the code
74 snippet below:
75
76 \snippet examples/graphicsview/basicgraphicslayouts/window.cpp 2
77
78 The first item we add to \c grid is placed in the top left cell,
79 spanning four rows. The next two items are placed in the second column,
80 and they span two rows. Each item's \l{QGraphicsWidget::}{maximumHeight()}
81 and \l{QGraphicsWidget::}{minimumHeight()} are set to be equal so that
82 they do not expand vertically. As a result, these items will not
83 fit vertically in their cells. So, we specify that they should be
84 vertically aligned in the center of the cell using Qt::AlignVCenter.
85
86 Finally, \c grid itself is added to \c windowLayout. Unlike
87 QGridLayout::addItem(), QGraphicsGridLayout::addItem() requires a row
88 and a column for its argument, specifying which cell the item should be
89 positioned in. Also, if the \c rowSpan and \c columnSpan arguments
90 are omitted, they will default to 1.
91
92 Note that we do not specify a parent for each \c LayoutItem that we
93 construct, as all these items will be added to \c windowLayout. When we
94 add an item to a layout, it will be automatically reparented to the widget
95 on which the layout is installed.
96
97 \snippet examples/graphicsview/basicgraphicslayouts/window.cpp 3
98
99 Now that we have set up \c grid and added it to \c windowLayout, we
100 install \c windowLayout onto the window object using
101 QGraphicsWidget::setLayout() and we set the window title.
102
103 \section1 LayoutItem Class Definition
104
105 The \c LayoutItem class is a subclass of QGraphicsLayoutItem and
106 QGraphicsItem. It has a constructor, a destructor, and some required
107 reimplementations.
108 Since it inherits QGraphicsLayoutItem it must reimplement
109 {QGraphicsLayoutItem::setGeometry()}{setGeometry()} and
110 {QGraphicsLayoutItem::sizeHint()}{sizeHint()}.
111 In addition to that it inherits QGraphicsItem, so it must reimplement
112 {QGraphicsItem::boundingRect()}{boundingRect()} and
113 {QGraphicsItem::paint()}{paint()}.
114
115 \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.h 0
116
117 The \c LayoutItem class also has a private instance of QPixmap, \c m_pix.
118
119 \section1 LayoutItem Class Implementation
120
121 In \c{LayoutItem}'s constructor, \c m_pix is instantiated and the
122 \c{block.png} image is loaded into it.
123
124 \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.cpp 0
125
126 We use the Q_UNUSED() macro to prevent the compiler from generating
127 warnings regarding unused parameters.
128
129 \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.cpp 1
130
131 The idea behind the \c paint() function is to paint the
132 background rect then paint a rect around the pixmap.
133
134 \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.cpp 2
135
136 The reimplementation of {QGraphicsItem::boundingRect()}{boundingRect()}
137 will set the top left corner at (0,0), and the size of it will be
138 the size of the layout items
139 {QGraphicsLayoutItem::geometry()}{geometry()}. This is the area that
140 we paint within.
141
142 \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.cpp 3
143
144
145 The reimplementation of {QGraphicsLayoutItem::setGeometry()}{setGeometry()}
146 simply calls its baseclass implementation. However, since this will change
147 the boundingRect we must also call
148 {QGraphicsItem::prepareGeometryChange()}{prepareGeometryChange()}.
149 Finally, we move the item according to \c geom.topLeft().
150
151 \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.cpp 4
152
153
154 Since we don't want the size of the item to be smaller than the pixmap, we
155 must make sure that we return a size hint that is larger than \c m_pix.
156 We also add some extra space around for borders that we will paint later.
157 Alternatively, you could scale the pixmap to prevent the item from
158 becoming smaller than the pixmap.
159 The preferred size is the same as the minimum size hint, while we set
160 maximum to be a large value
161
162 \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.cpp 5
163
164*/
Note: See TracBrowser for help on using the repository browser.