summaryrefslogtreecommitdiffstats
path: root/doc/src/porting4-canvas.qdoc
blob: 54861bc5a3e494451e00a92866c8ab2a14007022 (plain)
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
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** 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 Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain
** additional rights.  These rights are described in the Nokia Qt LGPL
** Exception version 1.1, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
**
**
**
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page graphicsview-porting.html
    \title Porting to Graphics View
    \contentspage {Porting Guides}{Contents}
    \previouspage Porting .ui Files to Qt 4
    \nextpage qt3to4 - The Qt 3 to 4 Porting Tool
    \ingroup porting
    \ingroup multimedia
    \brief Hints and tips to assist with porting canvas applications to the
    Graphics View framework.

    \keyword QGraphicsView GraphicsView Porting Graphics Canvas
    \since 4.2

    Graphics View provides a surface for managing and interacting with a large
    number of custom-made 2D graphical items, and a view widget for
    visualizing the items, with support for zooming and rotation. Graphics
    View was introduced in Qt 4.2, replacing its predecessor, QCanvas. For
    more on Graphics View, see \l{The Graphics View Framework}.

    This document walks through the steps needed, class by class and function
    by function, to port a QCanvas application to Graphics View.

    \tableofcontents

    Qt 4.2 provides two complete examples of Q3Canvas applications ported to
    Graphics View:

    \list
    \o \l{Ported Canvas Example}, the canvas example from Qt 3.
    \o \l{Ported Asteroids Example}, the Asteroids game from the Qt 3 demo.
    \endlist

    \section1 Introduction

        Conceptually, the Graphics View classes from Qt 4 and the Canvas
        classes from Qt 3 provide similar functionality using a similar
        design. Instead of "canvas", we use the term "scene". Otherwise, the
        class names and functions are almost the same as in Qt 3. The easiest
        classes to port will be QCanvas and QCanvasView. Experience shows that
        most time is spent porting the item classes, depending on the
        complexity of the QCanvasItem classes you have been using before.

        This porting guide will assume you have already ported your
        application to Qt 4, by making use of Q3Canvas. If you have not done
        so already, as a first step, run the \l qt3to4 tool on your
        project. This tool will automate the most tedious part of the porting
        effort.

        Some additional steps are usually required before your application
        will compile and run. You can read more about the porting process in
        \l{Porting to Qt 4}.

    \section1 Porting from Q3Canvas

        QGraphicsScene is the closest equivalent to Q3Canvas. There
        are some noticable differences in this new API: Whereas the
        Q3Canvas classes use integer precision, QGraphicsScene is
        entirely based on double coordinates, with graphical
        primitives such as QPointF instead of QPoint, QRectF instead
        of QRect, and QPolygonF and QPainterPath. The canvas area is
        defined by a scene rectangle, allowing negative coordinates,
        as opposed to Q3Canvas, which only defines a size (QSize), and
        whose top-left corner is always (0, 0).

        In addition, there is no explicit support for canvas tiles
        anymore; see \l{Porting scenes with tiles} for more
        information.  The chunks-based indexing system has been
        replaced with an implicitly maintained internal BSP tree.

        \section2 Porting table

        \table
        \header \o Q3Canvas \o QGraphicsScene

        \row \o Q3Canvas::Q3Canvas() \o There is no QPixmap based
           constructor, and the concept of tiles is gone. You can use
           QGraphicsScene::backgroundBrush to set a brush pattern for
           the background, or reimplement
           QGraphicsScene::drawBackground() in a QGraphicsScene
           subclass (see \l{Porting scenes with tiles}). In addition,
           the QGraphicsScene geometry is provided as a full
           QRectF. Instead of Q3Canvas(int width, int height), you can
           use QGraphicsScene(int top, int left, int width, int
           height).

        \row \o Q3Canvas::allItems() \o QGraphicsScene::items()
        returns a list of all items on the scene.

        \row \o Q3Canvas::backgroundColor() \o You can assign a color for the
        background through the QGraphicsScene::backgroundBrush
        or QGraphicsView::backgroundBrush properties.

        \row \o Q3Canvas::backgroundPixmap() \o You can set a tiled
        pixmap for the background through
        QGraphicsScene::backgroundBrush or
        QGraphicsView::backgroundBrush. For more control on the pixmap
        positioning, you can reimplement
        QGraphicsScene::drawBackground() or
        QGraphicsView::drawBackground().

        \row \o Q3Canvas::chunkSize() \o The closest equivalent to the
        chunks size in Q3Canvas is the depth of QGraphicsScene's BSP
        tree. QGraphicsScene assigns a depth automatically, and the
        size of each scene segment depends on this depth, and
        QGraphicsScene::sceneRect(). See
        QGraphicsScene::itemIndexMethod.

        \row \o Q3Canvas::collisions() \o QGraphicsScene provides
        several means to detect item collisions. The
        QGraphicsScene::items() overloads return items that collide
        with a point, a rectangle, a polygon, or an arbitrary vector
        path (QPainterPath). You can also call
        QGraphicsScene::collidingItems() to determine collision with
        an item.

        \row \o Q3Canvas::drawArea() \o The QGraphicsScene::render()
        function provides the original behavior
        Q3Canvas::drawArea(). In addition, you can pass a source
        rectangle for rendering only parts of the scene, and a
        destination rectangle for rendering onto designated area of
        the destination device. QGraphicsScene::render() can
        optionally transform the source rectangle to fit into the
        destination rectangle. See \l{Printing}

        \row \o Q3Canvas::onCanvas() \o The is no equivalent to this
        function in Graphics View. However, you can combine
        QGraphicsScene::sceneRect() and QRectF::intersects():
        \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 0

        \row \o Q3Canvas::rect() \o The equivalent,
        QGraphicsScene::sceneRect(), returns a QRectF (double
        precision coordinates). Its top-left corner can be an
        arbitrary coordinate (Q3Canvas::rect().topLeft() is always (0,
        0)).

        \row \o Q3Canvas::resize() \o You can call
        QGraphicsScene::setSceneRect(0, 0, width, height) instead.

        \row \o Q3Canvas::retune() \o See
        QGraphicsScene::itemIndexMethod. You can tune the indexing by
        setting a suitable sceneRect(). The optimal depth of
        QGraphicsScene's BSP tree is determined automatically.

        \row \o Q3Canvas::setAdvancePeriod() \o There is no concept of
        an advance period in the new API; instead, you can connect
        QTimer::timeout() to the QGraphicsScene::advance() slot to
        obtain similar functionality. This will cause all items'
        QGraphicsItem::advance() function to be called. See also
        QGraphicsItemAnimation.

        \row \o Q3Canvas::setAllChanged() \o You can call
        QGraphicsScene::update() with no arguments.

        \row \o Q3Canvas::setChanged() \o QGraphicsScene::update()
        will trigger a repaint of the whole scene, or parts of the
        scene.

        \row \o Q3Canvas::setDoubleBuffering() \o Q3Canvas' double
        buffering enabled cacheing of the scene contents in device
        (i.e., viewport) coordinates. This cache layer has been moved
        to the view instead; you can cache QGraphicsScene's background
        through
        QGraphicsView::setCacheMode(). QGraphicsView::resetCachedContent()
        will reset the areas of the cache that has changed.

        \row \o Q3Canvas::tile() \o See \l{Porting scenes with tiles}.

        \row \o Q3Canvas::setTiles() \o See \l{Porting scenes with tiles}.

        \row \o Q3Canvas::setUnchanged() \o There is no equivalent in
        Graphics View. This call can usually be removed with no side
        effects.

        \row \o Q3Canvas::setUpdatePeriod() \o There is no concept of an
        update period in the new API; instead, you can connect
        QTimer::timeout() to the QGraphicsScene::update() slot to obtain
        similar functionality. See also QGraphicsItemAnimation.

        \row \o Q3Canvas::size() \o
        \tt{QGraphicsScene::sceneRect().size()} returns a QSizeF, with
        double precision coordinates.

        \row \o Q3Canvas::validChunk() \o To determine if an area is
        inside the scene area or not, you can combine
        QRectF::intersects() with QGraphicsScene::sceneRect().

        \row \o Q3Canvas::resized() \o QGraphicsScene emits
        \l{QGraphicsScene::sceneRectChanged()}{sceneRectChanged()}
        whenever the scene rect changes.

        \row \o Q3Canvas::drawBackground() \o You can reimplement
        QGraphicsScene::drawBackground() to render the scene
        background. You can also reimplement
        QGraphicsView::drawBackground() to override this background if
        you need different backgrounds for different views.

        \row \o Q3Canvas::drawForeground() \o You can reimplement
        QGraphicsScene::drawForeground() to render the scene
        foreground. You can also reimplement
        QGraphicsView::drawForeground() to override this foreground if
        you need different foregrounds for different views.

        \endtable

        \section2 Porting scenes with tiles

        QGraphicsScene does not provide an API for tiles. However, you
        can achieve similar behavior by drawing pixmaps in a reimplementation of
        QGraphicsScene::drawBackground().

        Q3Canvas' tile support is based on providing one pixmap
        containing tiles of a fixed width and height, and then
        accessing them (reading and replacing tiles) by index. The
        tiles in the pixmap are arranged from the left to right, top
        to bottom.

        \table
        \row \i 0 \i 1 \i 2 \i 3
        \row \i 4 \i 5 \i 6 \i 7
        \endtable

        With Graphics View, this pixmap can be stored as a member of a
        subclass of QGraphicsScene. The three main functions that make
        out the public tile API can then be declared as new members of
        this class. Here is one example of how to implement tile support:

        \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 1

        Depending on how your scene uses tiles, you may be able to
        simplify this approach. In this example, we will try to mimic the behavior
        of the Q3Canvas functions.

        We start by creating a subclass of QGraphicsScene ("TileScene").
        In this class, we declare two of the tile
        functions from Q3Canvas, and we then add two helper function that returns the
        rectangle for a certain tile in our tile pixmap. We will use a
        two-dimensional vector of ints to keep track of what tiles should
        be used at what parts of the scene.

        \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 2

        In setTiles(), we store the pixmap and tile properties as
        members of the class. Then we resize the tiles vector
        to match the width and height of our tile grid.

        \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 3

        The setTile() function updates the tiles index, and then
        updates the corresponding rect in the scene by calling
        tileRect().

        \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 4

        The first tileRect() function returns a QRect for the tile at
        position (x, y).

        \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 5

        The second tileRect() function returns a QRect for a tile number.
        With these functions in place, we can implement the drawBackground()
        function.

        \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 6

        In drawBackground(), we redraw all tiles that have been
        exposed by intersecting each tile rect with the exposed background
        area.

     \section1 Porting from Q3CanvasView

        The closest equivalent to Q3CanvasView in Graphics View is
        called QGraphicsView.  In most cases, this is the easiest
        class to port. In addition to providing all of Q3CanvasView's
        functionality, QGraphicsView includes some useful new features. You
        can read more about this in QGraphicsView's documentation.

        \section2 Porting table

        \table
        \header \o Q3CanvasView \o QGraphicsView

        \row \o Q3CanvasView::Q3CanvasView() \o QGraphicsView provides
        the same constructors as Q3CanvasView, but without the name
        and flags arguments. You can set the name by calling
        \l{QWidget::setObjectName()}{setObjectName()}, and the flags by
        calling \l{QWidget::setWindowFlags()}{setWindowFlags()}.

        \row \o Q3CanvasView::canvas() \o QGraphicsView::scene()
        returns the scene that is currently associated with the
        view. QGraphicsScene also provides the opposite function,
        QGraphicsScene::views(), which returns a list of views
        observing the scene.

        \row \o Q3CanvasView::inverseWorldMatrix() \o You can call
        QGraphicsView::matrix() and QMatrix::inverted().
        QGraphicsView::mapToScene() and QGraphicsView::mapFromScene()
        allow transforming of viewport shapes to scene shapes, and
        vice versa.

        \row \o Q3CanvasView::setCanvas() \o QGraphicsView::setScene().

        \row \o Q3CanvasView::setWorldMatrix() \o
        QGraphicsView::setMatrix(), QGraphicsView::rotate(),
        QGraphicsView::scale(), QGraphicsView::shear() and
        QGraphicsView::translate().

        \row \o Q3CanvasView::worldMatrix() \o QGraphicsView::matrix()

        \row \o Q3CanvasView::drawContents() \o The
        QGraphicsView::drawBackground() function draws the background,
        QGraphicsView::drawItems() draws the items, and
        QGraphicsView::drawForeground() draws the foreground of the
        scene in scene coordinates. You can also reimplement these
        functions in QGraphicsScene.

        \endtable

        \section2 Other differences

        QGraphicsView can cache the visible contents of the scene,
        similar to how Q3Canvas::setDoubleBuffering() could cache the
        entire scene contents. You can call
        QGraphicsView::setCacheMode() to configure cacheing, and
        QGraphicsView::resetCachedContent() invalidates the cache.

        For improved navigation support, you can set a resize or
        transformation anchor through QGraphicsView::resizeAnchor and
        QGraphicsView::transformationAnchor. This allows you to easily
        rotate and zoom the view while keeping the center fixed, or
        zooming towards the position under the mouse cursor. In
        addition, if you set the QGraphicsView::dragMode of the view,
        QGraphicsView will provide rubber band selection or
        click-and-pull navigation using the
        \l{Qt::OpenHandCursor}{OpenHandCursor} and
        \l{Qt::ClosedHandCursor}{ClosedHandCursor} cursors.

    \section1 Porting from Q3CanvasItem

        The closest equivalent to Q3CanvasItem in Graphics View is
        called QGraphicsItem. Deriving from this class is very common,
        and because of that, porting from Q3CanvasItem often involves
        more work than Q3Canvas and Q3CanvasView.

        Q3CanvasItem has become easier to use, easier to subclass, and more
        powerful with QGraphicsItem. The key difference from Q3CanvasItem lies
        in event propagation and item groups, but you will also find several
        convenient new features, such as support for tooltips, cursors, item
        transformation and drag and drop. You can read all about QGraphicsItem
        in its own class documentation.

        This section starts with a table that shows how to port each function
        from Q3CanvasItem to QGraphicsItem. Immediately after that, each of
        Q3CanvasItem's standard subclasses have a section of their own.

        \table
        \header \o Q3CanvasItem \o QGraphicsItem

        \row \o Q3CanvasItem::advance() \o QGraphicsItem::advance() is
        provided for compatibility. QGraphicsScene::advance() calls
        QGraphicsItem::advance() for all items. See also QTimeLine and
        QGraphicsItemAnimation.

        \row \o Q3CanvasItem::animated() \o No equivalent; all items
        are advanced by QGraphicsScene::advance().

        \row \o Q3CanvasItem::boundingRectAdvanced() \o No
        equivalent. You can translate QGraphicsItem::boundingRect()
        instead (see QRectF::translate()).

        \row \o Q3CanvasItem::canvas() \o QGraphicsItem::scene()

        \row \o Q3CanvasItem::collidesWith() \o
        QGraphicsItem::collidesWithItem() and
        QGraphicsItem::collidesWithPath().

        \row \o Q3CanvasItem::collisions() \o
        QGraphicsItem::collidingItems() returns a list of all items
        that collide with an item. You can specify whether you want
        fast, rough estimate collision between bounding rectangles, or
        the slower, more accurate shapes.

        \row \o Q3CanvasItem::draw() \o QGraphicsItem::paint(). See
        also QStyleOptionGraphicsItem, QGraphicsScene::drawItems() and
        QGraphicsView::drawItems().

        \row \o Q3CanvasItem::hide() \o QGraphicsItem::hide() or
        QGraphicsItem::setVisible(). \l{QGraphicsItem}s are \e visible by
        default; \l{Q3CanvasItem}s, however, are not.

        \row \o Q3CanvasItem::isActive() \o No equivalent. To achieve
        similar behavior, you can add this property in a custom
        subclass of QGraphicsItem.

        \row \o Q3CanvasItem::isVisible() \o
        QGraphicsItem::isVisible(). \l{QGraphicsItem}s are \e visible by
        default; \l{Q3CanvasItem}s, however, are not.

        \row \o Q3CanvasItem::move() \o You can call
        QGraphicsItem::setPos() to change the position of the item.

        \row \o Q3CanvasItem::rtti() \o QGraphicsItem::type() and qgraphicsitem_cast().

        \row \o Q3CanvasItem::setActive() \o No equivalent.

        \row \o Q3CanvasItem::setAnimated() \o No equivalent; all
        items are by default "animated" (i.e.,
        QGraphicsScene::advance() advances all items on the scene).

        \row \o Q3CanvasItem::setCanvas() \o You can call
        QGraphicsScene::addItem(), or pass a pointer to the canvas to
        QGraphicsItem's constructor.

        \row \o Q3CanvasItem::setVelocity() \o No equivalent. You can
        add x and y velocity as member data of your class, and call
        QGraphicsItem::moveBy(x, y) from inside
        QGraphicsItem::advance(). See also QTimeLine and
        QGraphicsItemAnimation.

        \row \o Q3CanvasItem::setVisible() \o
        QGraphicsItem::setVisible(). \l{QGraphicsItem}s are \e visible by
        default; \l{Q3CanvasItem}s, however, are not.

        \row \o Q3CanvasItem::setX() \o QGraphicsItem::setPos()
        \row \o Q3CanvasItem::setY() \o QGraphicsItem::setPos()

        \row \o Q3CanvasItem::setXVelocity() \o No equivalent.
        \row \o Q3CanvasItem::setYVelocity() \o No equivalent.

        \row \o Q3CanvasItem::setZ() \o QGraphicsItem::setZValue()

        \row \o Q3CanvasItem::show() \o QGraphicsItem::show() or
        QGraphicsItem::setVisible(). \l{QGraphicsItem}s are \e visible by
        default; \l{Q3CanvasItem}s, however, are not.

        \row \o Q3CanvasItem::xVelocity() \o No equivalent.
        \row \o Q3CanvasItem::yVelocity() \o No equivalent.

        \endtable

        Note that some virtual functions that have passed on to
        QGraphicsItem have lost their virtuality. An example is
        Q3CanvasItem::moveBy(), which was often used to track movement of
        items. In this case, the virtual QGraphicsItem::itemChange() has
        taken over as a substitute.

        \section2 Q3CanvasPolygonalItem

            The closest equivalent to Q3CanvasPolygonalItem in
            Graphics View is called QAbstractGraphicsShapeItem. Unlike
            Q3CanvasPolygonalItem, it does not define area points
            (Q3CanvasPolygonalItem::areaPoints()); instead, each
            item's geometry is stored as a member of the subclasses.

            The Q3CanvasPolygonalItem::drawShape() function is no longer
            available; instead, you can set the brush and pen from inside
            QGraphicsItem::paint().

            \table
            \header \o Q3CanvasPolygonalItem \o QAbstractGraphicsShapeItem

            \row \o Q3CanvasPolygonalItem::areaPoints() \o No equivalent; each
            item's geometry is stored in the respective subclass.

            \row \o Q3CanvasPolygonalItem::areaPointsAdvanced() \o No
            equivalent; you can use QPolygonF::translate() or
            QPainterPath::translate() instead.

            \row \o Q3CanvasPolygonalItem::drawShape() \o
            QGraphicsItem::paint(). You can set the pen and brush from inside
            this function.

            \row \o Q3CanvasPolygonalItem::invalidate() \o Call
            QGraphicsItem::prepareGeometryChange() before changing the
            item's geometry.

            \row \o Q3CanvasPolygonalItem::isValid() \o No equivalent;
            items' geometry is always in a valid state.

            \row \o Q3CanvasPolygonalItem::winding() \o This function is only
            useful for polygon items and path items; see
            QGraphicsPolygonItem::fillRule(), and QPainterPath::fillRule() for
            QGraphicsPathItem.

            \endtable

        \section2 Q3CanvasEllipse

            The closest equivalent to Q3CanvasEllipse in Graphics View
            is called QGraphicsEllipseItem. The most noticable
            difference to QGraphicsEllipseItem is that the ellipse is
            not longer drawn centered around its position; rather, it
            is drawn using a bounding QRectF, just like
            QPainter::drawEllipse().

            For compatibility, you may want to shift the ellipse up and to the
            left to keep the ellipse centered. Example:

            \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 7

            Note: QGraphicsEllipseItem uses QAbstractGraphicsShapeItem::pen()
            for outlines, whereas Q3CanvasEllipse did not use
            Q3CanvasPolygonalItem::pen().

            \table
            \header \o Q3CanvasEllipse \o QGraphicsEllipseItem

            \row \o Q3CanvasEllipse::angleLength() \o QGraphicsEllipseItem::spanAngle()

            \row \o Q3CanvasEllipse::angleStart() \o QGraphicsEllipseItem::startAngle()

            \row \o Q3CanvasEllipse::setAngles() \o
            QGraphicsEllipseItem::setStartAngle() and
            QGraphicsEllipseItem::setSpanAngle()

            \row \o Q3CanvasEllipse::setSize() \o QGraphicsEllipseItem::setRect()

            \endtable

            \section2 Q3CanvasLine

            The closest equivalent to Q3CanvasLine in Graphics View is
            called QGraphicsLineItem.

            \table
            \header \o Q3CanvasLine \o QGraphicsLineItem

            \row \o Q3CanvasLine::endPoint() \o QGraphicsLineItem::line() and QLineF::p2()

            \row \o Q3CanvasLine::setPoints() \o QGraphicsLineItem::setLine()

            \row \o Q3CanvasLine::startPoint() \o QGraphicsLineItem::line()
            and QLineF::p1()

            \endtable

        \section2 Q3CanvasPolygon

            The closest equivalent to Q3CanvasPolygon in Graphics View
            is called QGraphicsPolygonItem.

            \table
            \header \o Q3CanvasPolygon \o QGraphicsPolygonItem

            \row \o Q3CanvasPolygon::areaPoints() \o
            QGraphicsPolygonItem::polygon() and QGraphicsItem::mapToParent()

            \row \o Q3CanvasPolygon::points() \o QGraphicsPolygonItem::polygon()

            \row \o Q3CanvasPolygon::setPoints() \o QGraphicsPolygonItem::setPolygon()

            \endtable

        \section2 Q3CanvasSpline

            The closest equivalent to Q3CanvasSpline in Graphics View
            is called QGraphicsPathItem. This item can be used to
            describe any type of path supported by QPainter.

            Q3CanvasSpline takes its control points as a Q3PointArray, but
            QPainterPath operates on a sequence of calls to
            QPainterPath::moveTo() and QPainterPath::cubicTo(). Here is how
            you can convert a bezier curve Q3PointArray to a QPainterPath:

            \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 8

            Note: QGraphicsPathItem uses QAbstractGraphicsShapeItem::pen() for
            outlines, whereas Q3CanvasSpline did not use
            Q3CanvasPolygonalItem::pen().

            \table
            \header \o Q3CanvasSpline \o QGraphicsPathItem

            \row \o Q3CanvasSpline::closed() \o No equivalent. You can call
            QPainterPath::closeSubPath() to close a subpath explicitly.

            \endtable

        \section2 Q3CanvasRectangle

            The closest equivalent to Q3CanvasRectangle in Graphics
            View is called QGraphicsRectItem.

            \table
            \header \o Q3CanvasRectangle \o QGraphicsRectItem

            \row \o Q3CanvasRectangle::height() \o QGraphicsRectItem::rect()
            and QRectF::height()

            \row \o Q3CanvasRectangle::setSize() \o QGraphicsRectItem::setRect()

            \row \o Q3CanvasRectangle::size() \o QGraphicsRectItem::rect() and QRectF::size()

            \row \o Q3CanvasRectangle::width() \o QGraphicsRectItem::rect() and QRectF::width()

            \row \o Q3CanvasRectangle::chunks() \o No equivalent.

            \endtable

        \section2 Q3CanvasSprite

            Q3CanvasSprite is the item class that differs the most from its
            Q3Canvas predecessor. The closest resemblance of Q3CanvasSprite in
            Graphics View is QGraphicsPixmapItem.

            Q3CanvasSprite supports animated pixmaps; QGraphicsPixmapItem,
            however, is a simple single-frame pixmap item. If all you need is
            a pixmap item, porting is straight-forward. If you do need the
            animation support, extra work is required; there is no direct
            porting approach.

            For the \l{Ported Asteroids Example}, a subclass of
            QGraphicsPixmapItem is used to replace Q3CanvasSprite, storing a
            list of pixmaps and a frame counter. The animation is advanced in
            QGraphicsItem::advance().

            \section3 Q3CanvasPixmap, Q3CanvasPixmapArray

                These classes have been removed from the API. You can use
                QPixmap instead of Q3CanvasPixmap, and QList instead of
                Q3CanvasPixmapArray.

                Q3CanvasPixmapArray included convenience for loading a
                sequence of pixmaps or masks using a path with a wildcard (see
                Q3CanvasPixmapArray::readPixmaps() and
                Q3CanvasPixmapArray::readCollisionMasks()). To achieve similar
                functionality using Graphics View, you can load the images by
                using QDir:

                \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 9

        \section2 Q3CanvasText

            Q3CanvasText has been split into two classes in Graphics View:
            QGraphicsSimpleTextItem and QGraphicsTextItem. For porting,
            QGraphicsSimpleTextItem should be adequate. QGraphicsTextItem
            provides advanced document structuring features similar to that of
            QTextEdit, and it also allows interaction (e.g., editing and
            selection).

            \table
            \header \o Q3CanvasText \o QGraphicsSimpleTextItem

            \row \o Q3CanvasText::color() \o QGraphicsSimpleTextItem::pen().

            \row \o Q3CanvasText::setColor() \o QGraphicsSimpleTextItem::setPen().

            \row \o Q3CanvasText::textFlags() \o Use QGraphicsTextItem instead.

            \endtable


        \section2 Q3CanvasItemList

            Use QList instead.

    \section1 Other Resources

    The \l{Porting to Qt 4.2's Graphics View} article in Qt Quarterly 21 covered the
    process of porting the Qt 3 canvas example to Qt 4.
    The result of this is the \l{Ported Canvas Example}{Ported Canvas} example.
*/