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

Last change on this file since 603 was 561, checked in by Dmitry A. Kuminov, 15 years ago

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