Long live Qt 4.5!

1 files changed, 703 insertions, 0 deletions

diff --git a/doc/src/porting4-canvas.qdoc b/doc/src/porting4-canvas.qdoc
new file mode 100644
index 0000000000..dcd1a1e9c4
--- /dev/null
+++ b/doc/src/porting4-canvas.qdoc
@@ -0,0 +1,703 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@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.
+*/