source: trunk/doc/src/porting4-canvas.qdoc@ 337

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

Initially imported qt-all-opensource-src-4.5.1 from Trolltech.
File size: 29.7 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4** Contact: Qt Software Information (qt-info@nokia.com)
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial Usage
10** Licensees holding valid Qt Commercial licenses may use this file in
11** accordance with the Qt Commercial License Agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and Nokia.
14**
15** GNU Lesser General Public License Usage
16** Alternatively, this file may be used under the terms of the GNU Lesser
17** General Public License version 2.1 as published by the Free Software
18** Foundation and appearing in the file LICENSE.LGPL included in the
19** packaging of this file. Please review the following information to
20** ensure the GNU Lesser General Public License version 2.1 requirements
21** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
22**
23** In addition, as a special exception, Nokia gives you certain
24** additional rights. These rights are described in the Nokia Qt LGPL
25** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
26** 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 are unsure which license is appropriate for your use, please
37** contact the sales department at qt-sales@nokia.com.
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42/*!
43 \page graphicsview-porting.html
44 \title Porting to Graphics View
45 \contentspage {Porting Guides}{Contents}
46 \previouspage Porting .ui Files to Qt 4
47 \nextpage qt3to4 - The Qt 3 to 4 Porting Tool
48 \ingroup porting
49 \ingroup multimedia
50 \brief Hints and tips to assist with porting canvas applications to the
51 Graphics View framework.
52
53 \keyword QGraphicsView GraphicsView Porting Graphics Canvas
54 \since 4.2
55
56 Graphics View provides a surface for managing and interacting with a large
57 number of custom-made 2D graphical items, and a view widget for
58 visualizing the items, with support for zooming and rotation. Graphics
59 View was introduced in Qt 4.2, replacing its predecessor, QCanvas. For
60 more on Graphics View, see \l{The Graphics View Framework}.
61
62 This document walks through the steps needed, class by class and function
63 by function, to port a QCanvas application to Graphics View.
64
65 \tableofcontents
66
67 Qt 4.2 provides two complete examples of Q3Canvas applications ported to
68 Graphics View:
69
70 \list
71 \o \l{Ported Canvas Example}, the canvas example from Qt 3.
72 \o \l{Ported Asteroids Example}, the Asteroids game from the Qt 3 demo.
73 \endlist
74
75 \section1 Introduction
76
77 Conceptually, the Graphics View classes from Qt 4 and the Canvas
78 classes from Qt 3 provide similar functionality using a similar
79 design. Instead of "canvas", we use the term "scene". Otherwise, the
80 class names and functions are almost the same as in Qt 3. The easiest
81 classes to port will be QCanvas and QCanvasView. Experience shows that
82 most time is spent porting the item classes, depending on the
83 complexity of the QCanvasItem classes you have been using before.
84
85 This porting guide will assume you have already ported your
86 application to Qt 4, by making use of Q3Canvas. If you have not done
87 so already, as a first step, run the \l qt3to4 tool on your
88 project. This tool will automate the most tedious part of the porting
89 effort.
90
91 Some additional steps are usually required before your application
92 will compile and run. You can read more about the porting process in
93 \l{Porting to Qt 4}.
94
95 \section1 Porting from Q3Canvas
96
97 QGraphicsScene is the closest equivalent to Q3Canvas. There
98 are some noticable differences in this new API: Whereas the
99 Q3Canvas classes use integer precision, QGraphicsScene is
100 entirely based on double coordinates, with graphical
101 primitives such as QPointF instead of QPoint, QRectF instead
102 of QRect, and QPolygonF and QPainterPath. The canvas area is
103 defined by a scene rectangle, allowing negative coordinates,
104 as opposed to Q3Canvas, which only defines a size (QSize), and
105 whose top-left corner is always (0, 0).
106
107 In addition, there is no explicit support for canvas tiles
108 anymore; see \l{Porting scenes with tiles} for more
109 information. The chunks-based indexing system has been
110 replaced with an implicitly maintained internal BSP tree.
111
112 \section2 Porting table
113
114 \table
115 \header \o Q3Canvas \o QGraphicsScene
116
117 \row \o Q3Canvas::Q3Canvas() \o There is no QPixmap based
118 constructor, and the concept of tiles is gone. You can use
119 QGraphicsScene::backgroundBrush to set a brush pattern for
120 the background, or reimplement
121 QGraphicsScene::drawBackground() in a QGraphicsScene
122 subclass (see \l{Porting scenes with tiles}). In addition,
123 the QGraphicsScene geometry is provided as a full
124 QRectF. Instead of Q3Canvas(int width, int height), you can
125 use QGraphicsScene(int top, int left, int width, int
126 height).
127
128 \row \o Q3Canvas::allItems() \o QGraphicsScene::items()
129 returns a list of all items on the scene.
130
131 \row \o Q3Canvas::backgroundColor() \o You can assign a color for the
132 background through the QGraphicsScene::backgroundBrush
133 or QGraphicsView::backgroundBrush properties.
134
135 \row \o Q3Canvas::backgroundPixmap() \o You can set a tiled
136 pixmap for the background through
137 QGraphicsScene::backgroundBrush or
138 QGraphicsView::backgroundBrush. For more control on the pixmap
139 positioning, you can reimplement
140 QGraphicsScene::drawBackground() or
141 QGraphicsView::drawBackground().
142
143 \row \o Q3Canvas::chunkSize() \o The closest equivalent to the
144 chunks size in Q3Canvas is the depth of QGraphicsScene's BSP
145 tree. QGraphicsScene assigns a depth automatically, and the
146 size of each scene segment depends on this depth, and
147 QGraphicsScene::sceneRect(). See
148 QGraphicsScene::itemIndexMethod.
149
150 \row \o Q3Canvas::collisions() \o QGraphicsScene provides
151 several means to detect item collisions. The
152 QGraphicsScene::items() overloads return items that collide
153 with a point, a rectangle, a polygon, or an arbitrary vector
154 path (QPainterPath). You can also call
155 QGraphicsScene::collidingItems() to determine collision with
156 an item.
157
158 \row \o Q3Canvas::drawArea() \o The QGraphicsScene::render()
159 function provides the original behavior
160 Q3Canvas::drawArea(). In addition, you can pass a source
161 rectangle for rendering only parts of the scene, and a
162 destination rectangle for rendering onto designated area of
163 the destination device. QGraphicsScene::render() can
164 optionally transform the source rectangle to fit into the
165 destination rectangle. See \l{Printing}
166
167 \row \o Q3Canvas::onCanvas() \o The is no equivalent to this
168 function in Graphics View. However, you can combine
169 QGraphicsScene::sceneRect() and QRectF::intersects():
170 \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 0
171
172 \row \o Q3Canvas::rect() \o The equivalent,
173 QGraphicsScene::sceneRect(), returns a QRectF (double
174 precision coordinates). Its top-left corner can be an
175 arbitrary coordinate (Q3Canvas::rect().topLeft() is always (0,
176 0)).
177
178 \row \o Q3Canvas::resize() \o You can call
179 QGraphicsScene::setSceneRect(0, 0, width, height) instead.
180
181 \row \o Q3Canvas::retune() \o See
182 QGraphicsScene::itemIndexMethod. You can tune the indexing by
183 setting a suitable sceneRect(). The optimal depth of
184 QGraphicsScene's BSP tree is determined automatically.
185
186 \row \o Q3Canvas::setAdvancePeriod() \o There is no concept of
187 an advance period in the new API; instead, you can connect
188 QTimer::timeout() to the QGraphicsScene::advance() slot to
189 obtain similar functionality. This will cause all items'
190 QGraphicsItem::advance() function to be called. See also
191 QGraphicsItemAnimation.
192
193 \row \o Q3Canvas::setAllChanged() \o You can call
194 QGraphicsScene::update() with no arguments.
195
196 \row \o Q3Canvas::setChanged() \o QGraphicsScene::update()
197 will trigger a repaint of the whole scene, or parts of the
198 scene.
199
200 \row \o Q3Canvas::setDoubleBuffering() \o Q3Canvas' double
201 buffering enabled cacheing of the scene contents in device
202 (i.e., viewport) coordinates. This cache layer has been moved
203 to the view instead; you can cache QGraphicsScene's background
204 through
205 QGraphicsView::setCacheMode(). QGraphicsView::resetCachedContent()
206 will reset the areas of the cache that has changed.
207
208 \row \o Q3Canvas::tile() \o See \l{Porting scenes with tiles}.
209
210 \row \o Q3Canvas::setTiles() \o See \l{Porting scenes with tiles}.
211
212 \row \o Q3Canvas::setUnchanged() \o There is no equivalent in
213 Graphics View. This call can usually be removed with no side
214 effects.
215
216 \row \o Q3Canvas::setUpdatePeriod() \o There is no concept of an
217 update period in the new API; instead, you can connect
218 QTimer::timeout() to the QGraphicsScene::update() slot to obtain
219 similar functionality. See also QGraphicsItemAnimation.
220
221 \row \o Q3Canvas::size() \o
222 \tt{QGraphicsScene::sceneRect().size()} returns a QSizeF, with
223 double precision coordinates.
224
225 \row \o Q3Canvas::validChunk() \o To determine if an area is
226 inside the scene area or not, you can combine
227 QRectF::intersects() with QGraphicsScene::sceneRect().
228
229 \row \o Q3Canvas::resized() \o QGraphicsScene emits
230 \l{QGraphicsScene::sceneRectChanged()}{sceneRectChanged()}
231 whenever the scene rect changes.
232
233 \row \o Q3Canvas::drawBackground() \o You can reimplement
234 QGraphicsScene::drawBackground() to render the scene
235 background. You can also reimplement
236 QGraphicsView::drawBackground() to override this background if
237 you need different backgrounds for different views.
238
239 \row \o Q3Canvas::drawForeground() \o You can reimplement
240 QGraphicsScene::drawForeground() to render the scene
241 foreground. You can also reimplement
242 QGraphicsView::drawForeground() to override this foreground if
243 you need different foregrounds for different views.
244
245 \endtable
246
247 \section2 Porting scenes with tiles
248
249 QGraphicsScene does not provide an API for tiles. However, you
250 can achieve similar behavior by drawing pixmaps in a reimplementation of
251 QGraphicsScene::drawBackground().
252
253 Q3Canvas' tile support is based on providing one pixmap
254 containing tiles of a fixed width and height, and then
255 accessing them (reading and replacing tiles) by index. The
256 tiles in the pixmap are arranged from the left to right, top
257 to bottom.
258
259 \table
260 \row \i 0 \i 1 \i 2 \i 3
261 \row \i 4 \i 5 \i 6 \i 7
262 \endtable
263
264 With Graphics View, this pixmap can be stored as a member of a
265 subclass of QGraphicsScene. The three main functions that make
266 out the public tile API can then be declared as new members of
267 this class. Here is one example of how to implement tile support:
268
269 \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 1
270
271 Depending on how your scene uses tiles, you may be able to
272 simplify this approach. In this example, we will try to mimic the behavior
273 of the Q3Canvas functions.
274
275 We start by creating a subclass of QGraphicsScene ("TileScene").
276 In this class, we declare two of the tile
277 functions from Q3Canvas, and we then add two helper function that returns the
278 rectangle for a certain tile in our tile pixmap. We will use a
279 two-dimensional vector of ints to keep track of what tiles should
280 be used at what parts of the scene.
281
282 \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 2
283
284 In setTiles(), we store the pixmap and tile properties as
285 members of the class. Then we resize the tiles vector
286 to match the width and height of our tile grid.
287
288 \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 3
289
290 The setTile() function updates the tiles index, and then
291 updates the corresponding rect in the scene by calling
292 tileRect().
293
294 \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 4
295
296 The first tileRect() function returns a QRect for the tile at
297 position (x, y).
298
299 \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 5
300
301 The second tileRect() function returns a QRect for a tile number.
302 With these functions in place, we can implement the drawBackground()
303 function.
304
305 \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 6
306
307 In drawBackground(), we redraw all tiles that have been
308 exposed by intersecting each tile rect with the exposed background
309 area.
310
311 \section1 Porting from Q3CanvasView
312
313 The closest equivalent to Q3CanvasView in Graphics View is
314 called QGraphicsView. In most cases, this is the easiest
315 class to port. In addition to providing all of Q3CanvasView's
316 functionality, QGraphicsView includes some useful new features. You
317 can read more about this in QGraphicsView's documentation.
318
319 \section2 Porting table
320
321 \table
322 \header \o Q3CanvasView \o QGraphicsView
323
324 \row \o Q3CanvasView::Q3CanvasView() \o QGraphicsView provides
325 the same constructors as Q3CanvasView, but without the name
326 and flags arguments. You can set the name by calling
327 \l{QWidget::setObjectName()}{setObjectName()}, and the flags by
328 calling \l{QWidget::setWindowFlags()}{setWindowFlags()}.
329
330 \row \o Q3CanvasView::canvas() \o QGraphicsView::scene()
331 returns the scene that is currently associated with the
332 view. QGraphicsScene also provides the opposite function,
333 QGraphicsScene::views(), which returns a list of views
334 observing the scene.
335
336 \row \o Q3CanvasView::inverseWorldMatrix() \o You can call
337 QGraphicsView::matrix() and QMatrix::inverted().
338 QGraphicsView::mapToScene() and QGraphicsView::mapFromScene()
339 allow transforming of viewport shapes to scene shapes, and
340 vice versa.
341
342 \row \o Q3CanvasView::setCanvas() \o QGraphicsView::setScene().
343
344 \row \o Q3CanvasView::setWorldMatrix() \o
345 QGraphicsView::setMatrix(), QGraphicsView::rotate(),
346 QGraphicsView::scale(), QGraphicsView::shear() and
347 QGraphicsView::translate().
348
349 \row \o Q3CanvasView::worldMatrix() \o QGraphicsView::matrix()
350
351 \row \o Q3CanvasView::drawContents() \o The
352 QGraphicsView::drawBackground() function draws the background,
353 QGraphicsView::drawItems() draws the items, and
354 QGraphicsView::drawForeground() draws the foreground of the
355 scene in scene coordinates. You can also reimplement these
356 functions in QGraphicsScene.
357
358 \endtable
359
360 \section2 Other differences
361
362 QGraphicsView can cache the visible contents of the scene,
363 similar to how Q3Canvas::setDoubleBuffering() could cache the
364 entire scene contents. You can call
365 QGraphicsView::setCacheMode() to configure cacheing, and
366 QGraphicsView::resetCachedContent() invalidates the cache.
367
368 For improved navigation support, you can set a resize or
369 transformation anchor through QGraphicsView::resizeAnchor and
370 QGraphicsView::transformationAnchor. This allows you to easily
371 rotate and zoom the view while keeping the center fixed, or
372 zooming towards the position under the mouse cursor. In
373 addition, if you set the QGraphicsView::dragMode of the view,
374 QGraphicsView will provide rubber band selection or
375 click-and-pull navigation using the
376 \l{Qt::OpenHandCursor}{OpenHandCursor} and
377 \l{Qt::ClosedHandCursor}{ClosedHandCursor} cursors.
378
379 \section1 Porting from Q3CanvasItem
380
381 The closest equivalent to Q3CanvasItem in Graphics View is
382 called QGraphicsItem. Deriving from this class is very common,
383 and because of that, porting from Q3CanvasItem often involves
384 more work than Q3Canvas and Q3CanvasView.
385
386 Q3CanvasItem has become easier to use, easier to subclass, and more
387 powerful with QGraphicsItem. The key difference from Q3CanvasItem lies
388 in event propagation and item groups, but you will also find several
389 convenient new features, such as support for tooltips, cursors, item
390 transformation and drag and drop. You can read all about QGraphicsItem
391 in its own class documentation.
392
393 This section starts with a table that shows how to port each function
394 from Q3CanvasItem to QGraphicsItem. Immediately after that, each of
395 Q3CanvasItem's standard subclasses have a section of their own.
396
397 \table
398 \header \o Q3CanvasItem \o QGraphicsItem
399
400 \row \o Q3CanvasItem::advance() \o QGraphicsItem::advance() is
401 provided for compatibility. QGraphicsScene::advance() calls
402 QGraphicsItem::advance() for all items. See also QTimeLine and
403 QGraphicsItemAnimation.
404
405 \row \o Q3CanvasItem::animated() \o No equivalent; all items
406 are advanced by QGraphicsScene::advance().
407
408 \row \o Q3CanvasItem::boundingRectAdvanced() \o No
409 equivalent. You can translate QGraphicsItem::boundingRect()
410 instead (see QRectF::translate()).
411
412 \row \o Q3CanvasItem::canvas() \o QGraphicsItem::scene()
413
414 \row \o Q3CanvasItem::collidesWith() \o
415 QGraphicsItem::collidesWithItem() and
416 QGraphicsItem::collidesWithPath().
417
418 \row \o Q3CanvasItem::collisions() \o
419 QGraphicsItem::collidingItems() returns a list of all items
420 that collide with an item. You can specify whether you want
421 fast, rough estimate collision between bounding rectangles, or
422 the slower, more accurate shapes.
423
424 \row \o Q3CanvasItem::draw() \o QGraphicsItem::paint(). See
425 also QStyleOptionGraphicsItem, QGraphicsScene::drawItems() and
426 QGraphicsView::drawItems().
427
428 \row \o Q3CanvasItem::hide() \o QGraphicsItem::hide() or
429 QGraphicsItem::setVisible(). \l{QGraphicsItem}s are \e visible by
430 default; \l{Q3CanvasItem}s, however, are not.
431
432 \row \o Q3CanvasItem::isActive() \o No equivalent. To achieve
433 similar behavior, you can add this property in a custom
434 subclass of QGraphicsItem.
435
436 \row \o Q3CanvasItem::isVisible() \o
437 QGraphicsItem::isVisible(). \l{QGraphicsItem}s are \e visible by
438 default; \l{Q3CanvasItem}s, however, are not.
439
440 \row \o Q3CanvasItem::move() \o You can call
441 QGraphicsItem::setPos() to change the position of the item.
442
443 \row \o Q3CanvasItem::rtti() \o QGraphicsItem::type() and qgraphicsitem_cast().
444
445 \row \o Q3CanvasItem::setActive() \o No equivalent.
446
447 \row \o Q3CanvasItem::setAnimated() \o No equivalent; all
448 items are by default "animated" (i.e.,
449 QGraphicsScene::advance() advances all items on the scene).
450
451 \row \o Q3CanvasItem::setCanvas() \o You can call
452 QGraphicsScene::addItem(), or pass a pointer to the canvas to
453 QGraphicsItem's constructor.
454
455 \row \o Q3CanvasItem::setVelocity() \o No equivalent. You can
456 add x and y velocity as member data of your class, and call
457 QGraphicsItem::moveBy(x, y) from inside
458 QGraphicsItem::advance(). See also QTimeLine and
459 QGraphicsItemAnimation.
460
461 \row \o Q3CanvasItem::setVisible() \o
462 QGraphicsItem::setVisible(). \l{QGraphicsItem}s are \e visible by
463 default; \l{Q3CanvasItem}s, however, are not.
464
465 \row \o Q3CanvasItem::setX() \o QGraphicsItem::setPos()
466 \row \o Q3CanvasItem::setY() \o QGraphicsItem::setPos()
467
468 \row \o Q3CanvasItem::setXVelocity() \o No equivalent.
469 \row \o Q3CanvasItem::setYVelocity() \o No equivalent.
470
471 \row \o Q3CanvasItem::setZ() \o QGraphicsItem::setZValue()
472
473 \row \o Q3CanvasItem::show() \o QGraphicsItem::show() or
474 QGraphicsItem::setVisible(). \l{QGraphicsItem}s are \e visible by
475 default; \l{Q3CanvasItem}s, however, are not.
476
477 \row \o Q3CanvasItem::xVelocity() \o No equivalent.
478 \row \o Q3CanvasItem::yVelocity() \o No equivalent.
479
480 \endtable
481
482 Note that some virtual functions that have passed on to
483 QGraphicsItem have lost their virtuality. An example is
484 Q3CanvasItem::moveBy(), which was often used to track movement of
485 items. In this case, the virtual QGraphicsItem::itemChange() has
486 taken over as a substitute.
487
488 \section2 Q3CanvasPolygonalItem
489
490 The closest equivalent to Q3CanvasPolygonalItem in
491 Graphics View is called QAbstractGraphicsShapeItem. Unlike
492 Q3CanvasPolygonalItem, it does not define area points
493 (Q3CanvasPolygonalItem::areaPoints()); instead, each
494 item's geometry is stored as a member of the subclasses.
495
496 The Q3CanvasPolygonalItem::drawShape() function is no longer
497 available; instead, you can set the brush and pen from inside
498 QGraphicsItem::paint().
499
500 \table
501 \header \o Q3CanvasPolygonalItem \o QAbstractGraphicsShapeItem
502
503 \row \o Q3CanvasPolygonalItem::areaPoints() \o No equivalent; each
504 item's geometry is stored in the respective subclass.
505
506 \row \o Q3CanvasPolygonalItem::areaPointsAdvanced() \o No
507 equivalent; you can use QPolygonF::translate() or
508 QPainterPath::translate() instead.
509
510 \row \o Q3CanvasPolygonalItem::drawShape() \o
511 QGraphicsItem::paint(). You can set the pen and brush from inside
512 this function.
513
514 \row \o Q3CanvasPolygonalItem::invalidate() \o Call
515 QGraphicsItem::prepareGeometryChange() before changing the
516 item's geometry.
517
518 \row \o Q3CanvasPolygonalItem::isValid() \o No equivalent;
519 items' geometry is always in a valid state.
520
521 \row \o Q3CanvasPolygonalItem::winding() \o This function is only
522 useful for polygon items and path items; see
523 QGraphicsPolygonItem::fillRule(), and QPainterPath::fillRule() for
524 QGraphicsPathItem.
525
526 \endtable
527
528 \section2 Q3CanvasEllipse
529
530 The closest equivalent to Q3CanvasEllipse in Graphics View
531 is called QGraphicsEllipseItem. The most noticable
532 difference to QGraphicsEllipseItem is that the ellipse is
533 not longer drawn centered around its position; rather, it
534 is drawn using a bounding QRectF, just like
535 QPainter::drawEllipse().
536
537 For compatibility, you may want to shift the ellipse up and to the
538 left to keep the ellipse centered. Example:
539
540 \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 7
541
542 Note: QGraphicsEllipseItem uses QAbstractGraphicsShapeItem::pen()
543 for outlines, whereas Q3CanvasEllipse did not use
544 Q3CanvasPolygonalItem::pen().
545
546 \table
547 \header \o Q3CanvasEllipse \o QGraphicsEllipseItem
548
549 \row \o Q3CanvasEllipse::angleLength() \o QGraphicsEllipseItem::spanAngle()
550
551 \row \o Q3CanvasEllipse::angleStart() \o QGraphicsEllipseItem::startAngle()
552
553 \row \o Q3CanvasEllipse::setAngles() \o
554 QGraphicsEllipseItem::setStartAngle() and
555 QGraphicsEllipseItem::setSpanAngle()
556
557 \row \o Q3CanvasEllipse::setSize() \o QGraphicsEllipseItem::setRect()
558
559 \endtable
560
561 \section2 Q3CanvasLine
562
563 The closest equivalent to Q3CanvasLine in Graphics View is
564 called QGraphicsLineItem.
565
566 \table
567 \header \o Q3CanvasLine \o QGraphicsLineItem
568
569 \row \o Q3CanvasLine::endPoint() \o QGraphicsLineItem::line() and QLineF::p2()
570
571 \row \o Q3CanvasLine::setPoints() \o QGraphicsLineItem::setLine()
572
573 \row \o Q3CanvasLine::startPoint() \o QGraphicsLineItem::line()
574 and QLineF::p1()
575
576 \endtable
577
578 \section2 Q3CanvasPolygon
579
580 The closest equivalent to Q3CanvasPolygon in Graphics View
581 is called QGraphicsPolygonItem.
582
583 \table
584 \header \o Q3CanvasPolygon \o QGraphicsPolygonItem
585
586 \row \o Q3CanvasPolygon::areaPoints() \o
587 QGraphicsPolygonItem::polygon() and QGraphicsItem::mapToParent()
588
589 \row \o Q3CanvasPolygon::points() \o QGraphicsPolygonItem::polygon()
590
591 \row \o Q3CanvasPolygon::setPoints() \o QGraphicsPolygonItem::setPolygon()
592
593 \endtable
594
595 \section2 Q3CanvasSpline
596
597 The closest equivalent to Q3CanvasSpline in Graphics View
598 is called QGraphicsPathItem. This item can be used to
599 describe any type of path supported by QPainter.
600
601 Q3CanvasSpline takes its control points as a Q3PointArray, but
602 QPainterPath operates on a sequence of calls to
603 QPainterPath::moveTo() and QPainterPath::cubicTo(). Here is how
604 you can convert a bezier curve Q3PointArray to a QPainterPath:
605
606 \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 8
607
608 Note: QGraphicsPathItem uses QAbstractGraphicsShapeItem::pen() for
609 outlines, whereas Q3CanvasSpline did not use
610 Q3CanvasPolygonalItem::pen().
611
612 \table
613 \header \o Q3CanvasSpline \o QGraphicsPathItem
614
615 \row \o Q3CanvasSpline::closed() \o No equivalent. You can call
616 QPainterPath::closeSubPath() to close a subpath explicitly.
617
618 \endtable
619
620 \section2 Q3CanvasRectangle
621
622 The closest equivalent to Q3CanvasRectangle in Graphics
623 View is called QGraphicsRectItem.
624
625 \table
626 \header \o Q3CanvasRectangle \o QGraphicsRectItem
627
628 \row \o Q3CanvasRectangle::height() \o QGraphicsRectItem::rect()
629 and QRectF::height()
630
631 \row \o Q3CanvasRectangle::setSize() \o QGraphicsRectItem::setRect()
632
633 \row \o Q3CanvasRectangle::size() \o QGraphicsRectItem::rect() and QRectF::size()
634
635 \row \o Q3CanvasRectangle::width() \o QGraphicsRectItem::rect() and QRectF::width()
636
637 \row \o Q3CanvasRectangle::chunks() \o No equivalent.
638
639 \endtable
640
641 \section2 Q3CanvasSprite
642
643 Q3CanvasSprite is the item class that differs the most from its
644 Q3Canvas predecessor. The closest resemblance of Q3CanvasSprite in
645 Graphics View is QGraphicsPixmapItem.
646
647 Q3CanvasSprite supports animated pixmaps; QGraphicsPixmapItem,
648 however, is a simple single-frame pixmap item. If all you need is
649 a pixmap item, porting is straight-forward. If you do need the
650 animation support, extra work is required; there is no direct
651 porting approach.
652
653 For the \l{Ported Asteroids Example}, a subclass of
654 QGraphicsPixmapItem is used to replace Q3CanvasSprite, storing a
655 list of pixmaps and a frame counter. The animation is advanced in
656 QGraphicsItem::advance().
657
658 \section3 Q3CanvasPixmap, Q3CanvasPixmapArray
659
660 These classes have been removed from the API. You can use
661 QPixmap instead of Q3CanvasPixmap, and QList instead of
662 Q3CanvasPixmapArray.
663
664 Q3CanvasPixmapArray included convenience for loading a
665 sequence of pixmaps or masks using a path with a wildcard (see
666 Q3CanvasPixmapArray::readPixmaps() and
667 Q3CanvasPixmapArray::readCollisionMasks()). To achieve similar
668 functionality using Graphics View, you can load the images by
669 using QDir:
670
671 \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 9
672
673 \section2 Q3CanvasText
674
675 Q3CanvasText has been split into two classes in Graphics View:
676 QGraphicsSimpleTextItem and QGraphicsTextItem. For porting,
677 QGraphicsSimpleTextItem should be adequate. QGraphicsTextItem
678 provides advanced document structuring features similar to that of
679 QTextEdit, and it also allows interaction (e.g., editing and
680 selection).
681
682 \table
683 \header \o Q3CanvasText \o QGraphicsSimpleTextItem
684
685 \row \o Q3CanvasText::color() \o QGraphicsSimpleTextItem::pen().
686
687 \row \o Q3CanvasText::setColor() \o QGraphicsSimpleTextItem::setPen().
688
689 \row \o Q3CanvasText::textFlags() \o Use QGraphicsTextItem instead.
690
691 \endtable
692
693
694 \section2 Q3CanvasItemList
695
696 Use QList instead.
697
698 \section1 Other Resources
699
700 The \l{Porting to Qt 4.2's Graphics View} article in Qt Quarterly 21 covered the
701 process of porting the Qt 3 canvas example to Qt 4.
702 The result of this is the \l{Ported Canvas Example}{Ported Canvas} example.
703*/
Note: See TracBrowser for help on using the repository browser.