/****************************************************************************

**

** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** 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

    \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