Update copyright headers
[qt:qt.git] / doc / src / examples / basicgraphicslayouts.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29     \example graphicsview/basicgraphicslayouts
30     \title Basic Graphics Layouts Example
31
32     \brief 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 \l{QGraphicsItem::}{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     \l{QGraphicsLayoutItem::}{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 \l{QGraphicsLayoutItem::setGeometry()}{setGeometry()}
146     simply calls its baseclass implementation. However, since this will change
147     the boundingRect we must also call
148     \l{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 */