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