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
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
|
/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the Technology Preview License Agreement accompanying
** this package.
**
** GNU Free Documentation License
** 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.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\example graphicsview/collidingmice
\title Colliding Mice Example
The Colliding Mice example shows how to use the Graphics View
framework to implement animated items and detect collision between
items.
\image collidingmice-example.png
Graphics View provides the QGraphicsScene class for managing and
interacting with a large number of custom-made 2D graphical items
derived from the QGraphicsItem class, and a QGraphicsView widget
for visualizing the items, with support for zooming and rotation.
The example consists of an item class and a main function:
the \c Mouse class represents the individual mice extending
QGraphicsItem, and the \c main() function provides the main
application window.
We will first review the \c Mouse class to see how to animate
items and detect item collision, and then we will review the \c
main() function to see how to put the items into a scene and how to
implement the corresponding view.
\section1 Mouse Class Definition
The \c mouse class inherits from QGraphicsItem. The
QGraphicsItem class is the base class for all graphical items in
the Graphics View framework, and provides a light-weight
foundation for writing your own custom items.
\snippet examples/graphicsview/collidingmice/mouse.h 0
When writing a custom graphics item, you must implement
QGraphicsItem's two pure virtual public functions: \l
{QGraphicsItem::}{boundingRect()}, which returns an estimate of
the area painted by the item, and \l {QGraphicsItem::}{paint()},
which implements the actual painting. In addition, we reimplement
the \l {QGraphicsItem::}{shape()} and \l {QGraphicsItem::}{advance()}.
We reimplement \l {QGraphicsItem::}{shape()} to return an accurate
shape of our mouse item; the default implementation simply returns
the item's bounding rectangle. We reimplement \l {QGraphicsItem::}{advance()}
to handle the animation so it all happens on one update.
\section1 Mouse Class Definition
When constructing a mouse item, we first ensure that all the item's
private variables are properly initialized:
\snippet examples/graphicsview/collidingmice/mouse.cpp 0
To calculate the various components of the mouse's color, we use
the global qrand() function which is a thread-safe version of the
standard C++ rand() function.
Then we call the \l {QGraphicsItem::setRotation()}{setRotation()} function
inherited from QGraphicsItem. Items live in their own local
coordinate system. Their coordinates are usually centered around
(0, 0), and this is also the center for all transformations. By
calling the item's \l {QGraphicsItem::setRotation()}{setRotation()} function
we alter the direction in which the mouse will start moving.
When the QGraphicsScene decides to advance the scene a frame it will call
QGraphicsItem::advance() on each of the items. This enables us to animate
our mouse using our reimplementation of the advance() function.
\snippet examples/graphicsview/collidingmice/mouse.cpp 4
\snippet examples/graphicsview/collidingmice/mouse.cpp 5
\snippet examples/graphicsview/collidingmice/mouse.cpp 6
First, we don't bother doing any advance if the step is 0 since we want to our advance in
the actual advance (advance() is called twice, once with step == 0 indicating that items
are about to advance and with step == 1 for the actual advance). We also ensure that the
mice stays within a circle with a radius of 150 pixels.
Note the \l {QGraphicsItem::mapFromScene()}{mapFromScene()}
function provided by QGraphicsItem. This function maps a position
given in \e scene coordinates, to the item's coordinate system.
\snippet examples/graphicsview/collidingmice/mouse.cpp 7
\snippet examples/graphicsview/collidingmice/mouse.cpp 8
\snippet examples/graphicsview/collidingmice/mouse.cpp 9
\codeline
\snippet examples/graphicsview/collidingmice/mouse.cpp 10
Then we try to avoid colliding with other mice.
\snippet examples/graphicsview/collidingmice/mouse.cpp 11
Finally, we calculate the mouse's speed and its eye direction (for
use when painting the mouse), and set its new position.
The position of an item describes its origin (local coordinate (0,
0)) in the parent coordinates. The \l {QGraphicsItem::setPos()}
function sets the position of the item to the given position in
the parent's coordinate system. For items with no parent, the
given position is interpreted as scene coordinates. QGraphicsItem
also provides a \l {QGraphicsItem::}{mapToParent()} function to
map a position given in item coordinates, to the parent's
coordinate system. If the item has no parent, the position will be
mapped to the scene's coordinate system instead.
Then it is time to provide an implementation for the pure virtual
functions inherited from QGraphicsItem. Let's first take a look at
the \l {QGraphicsItem::}{boundingRect()} function:
\snippet examples/graphicsview/collidingmice/mouse.cpp 1
The \l {QGraphicsItem::boundingRect()}{boundingRect()} function
defines the outer bounds of the item as a rectangle. Note that the
Graphics View framework uses the bounding rectangle to determine
whether the item requires redrawing, so all painting must be
restricted inside this rectangle.
\snippet examples/graphicsview/collidingmice/mouse.cpp 3
The Graphics View framework calls the \l
{QGraphicsItem::paint()}{paint()} function to paint the contents
of the item; the function paints the item in local coordinates.
Note the painting of the ears: Whenever a mouse item collides with
other mice items its ears are filled with red; otherwise they are
filled with dark yellow. We use the
QGraphicsScene::collidingItems() function to check if there are
any colliding mice. The actual collision detection is handled by
the Graphics View framework using shape-shape intersection. All we
have to do is to ensure that the QGraphicsItem::shape() function
returns an accurate shape for our item:
\snippet examples/graphicsview/collidingmice/mouse.cpp 2
Because the complexity of arbitrary shape-shape intersection grows
with an order of magnitude when the shapes are complex, this
operation can be noticably time consuming. An alternative approach
is to reimplement the \l
{QGraphicsItem::collidesWithItem()}{collidesWithItem()} function
to provide your own custom item and shape collision algorithm.
This completes the \c Mouse class implementation, it is now ready
for use. Let's take a look at the \c main() function to see how to
implement a scene for the mice and a view for displaying the
contents of the scene.
\section1 The Main() Function
In this example we have chosen to let the \c main() function
provide the main application window, creating the items and the
scene, putting the items into the scene and creating a
corresponding view.
\snippet examples/graphicsview/collidingmice/main.cpp 0
First, we create an application object and call the global
qsrand() function to specify the seed used to generate a new
random number sequence of pseudo random integers with the
previously mentioned qrand() function.
Then it is time to create the scene:
\snippet examples/graphicsview/collidingmice/main.cpp 1
The QGraphicsScene class serves as a container for
QGraphicsItems. It also provides functionality that lets you
efficiently determine the location of items as well as determining
which items that are visible within an arbitrary area on the
scene.
When creating a scene it is recommended to set the scene's
rectangle, i.e., the rectangle that defines the extent of the
scene. It is primarily used by QGraphicsView to determine the
view's default scrollable area, and by QGraphicsScene to manage
item indexing. If not explicitly set, the scene's default
rectangle will be the largest bounding rectangle of all the items
on the scene since the scene was created (i.e., the rectangle will
grow when items are added or moved in the scene, but it will never
shrink).
\snippet examples/graphicsview/collidingmice/main.cpp 2
The item index function is used to speed up item discovery. \l
{QGraphicsScene::NoIndex}{NoIndex} implies that item location is
of linear complexity, as all items on the scene are
searched. Adding, moving and removing items, however, is done in
constant time. This approach is ideal for dynamic scenes, where
many items are added, moved or removed continuously. The
alternative is \l {QGraphicsScene::BspTreeIndex}{BspTreeIndex}
which makes use of binary search resulting in item location
algorithms that are of an order closer to logarithmic complexity.
\snippet examples/graphicsview/collidingmice/main.cpp 3
Then we add the mice to the scene.
\snippet examples/graphicsview/collidingmice/main.cpp 4
To be able to view the scene we must also create a QGraphicsView
widget. The QGraphicsView class visualizes the contents of a scene
in a scrollable viewport. We also ensure that the contents is
rendered using antialiasing, and we create the cheese background
by setting the view's background brush.
The image used for the background is stored as a binary file in
the application's executable using Qt's \l {The Qt Resource
System}{resource system}. The QPixmap constructor accepts both
file names that refer to actual files on disk and file names that
refer to the application's embedded resources.
\snippet examples/graphicsview/collidingmice/main.cpp 5
Then we set the cache mode; QGraphicsView can cache pre-rendered
content in a pixmap, which is then drawn onto the viewport. The
purpose of such caching is to speed up the total rendering time
for areas that are slow to render, e.g., texture, gradient and
alpha blended backgrounds. The \l
{QGraphicsView::CacheMode}{CacheMode} property holds which parts
of the view that are cached, and the \l
{QGraphicsView::CacheBackground}{CacheBackground} flag enables
caching of the view's background.
By setting the \l {QGraphicsView::dragMode}{dragMode} property we
define what should happen when the user clicks on the scene
background and drags the mouse. The \l
{QGraphicsView::ScrollHandDrag}{ScrollHandDrag} flag makes the
cursor change into a pointing hand, and dragging the mouse around
will scroll the scrollbars.
\snippet examples/graphicsview/collidingmice/main.cpp 6
In the end, we set the application window's title and size before
we enter the main event loop using the QApplication::exec()
function.
Finally, we create a QTimer and connect its timeout() signal to the advance()
slot of the scene. Every time the timer fires, the scene will advance one frame.
We then tell the timer to fire every 1000/33 millisecond. This will
give us a frame rate of 30 frames a second, which is fast enough for most animations.
Doing the animation with a single timer connect to advance the scene ensures that all the
mice are moved at one point and, more importantly, only one update is sent to the screen
after all the mice have moved.
*/
|
