|  | Home · All Classes · Main Classes · Grouped Classes · Modules · Functions |

# Porting to Graphics View

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

- Introduction
- Porting from Q3Canvas
- Porting from Q3CanvasView
- Porting from Q3CanvasItem

- Q3CanvasPolygonalItem
- Q3CanvasEllipse
- Q3CanvasLine
- Q3CanvasPolygon
- Q3CanvasSpline
- Q3CanvasRectangle
- Q3CanvasSprite

- Q3CanvasPixmap, Q3CanvasPixmapArray

- Q3CanvasText
- Q3CanvasItemList

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

- Ported Canvas Example, the canvas example from Qt 3.
- Ported Asteroids Example, the Asteroids game from the Qt 3 demo.

## 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 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 Porting to Qt 4.

## Porting from Q3Canvas

QGraphicsScene is the equivalent of 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.

In addition, there is no explicit support for canvas tiles anymore, and the chunks system has been replaced with an implicitly maintained internal BSP tree.

Q3Canvas | QGraphicsScene
--- | ---
Q3Canvas::Q3Canvas() | 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. 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).
Q3Canvas::allItems() | QGraphicsScene::items()
Q3Canvas::backgroundColor() | QGraphicsScene::backgroundBrush or QGraphicsView::backgroundBrush
Q3Canvas::backgroundPixmap() | QGraphicsScene::backgroundBrush or QGraphicsView::backgroundBrush
Q3Canvas::chunkSize() | See QGraphicsScene::itemIndexMethod.
Q3Canvas::collisions() | QGraphicsScene::items()
Q3Canvas::drawArea() | QGraphicsScene::render()
Q3Canvas::onCanvas() | QGraphicsScene::sceneRect() and QRectF::contains().
Q3Canvas::rect() | QGraphicsScene::sceneRect()
Q3Canvas::resize() | QGraphicsScene::setSceneRect()
Q3Canvas::retune() | See QGraphicsScene::itemIndexMethod.
Q3Canvas::setAdvancePeriod() | 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.
Q3Canvas::setAllChanged() | QGraphicsScene::update() with no arguments.
Q3Canvas::setChanged() | QGraphicsScene::update()
Q3Canvas::setDoubleBuffering() | Double buffering is implicitly enabled in all widget in Qt 4. See Qt::WA_PaintOnScreen for how to disable double buffering.
Q3Canvas::tile() | No equivalent. You can use QGraphicsScene::backgroundBrush() or QGraphicsScene::drawBackground() instead.
Q3Canvas::setTiles() | No equivalent. You can use QGraphicsScene::backgroundBrush() or QGraphicsScene::drawBackground() instead.
Q3Canvas::setUnchanged() | No equivalent. This call can usually be removed with no side effects.
Q3Canvas::setUpdatePeriod() | 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.
Q3Canvas::size() | QGraphicsScene::sceneRect() and QRectF::size().
Q3Canvas::validChunk() | QGraphicsScene::sceneRect() and QRectF::contains().
Q3Canvas::resized() | QGraphicsScene::sceneRectChanged()
Q3Canvas::drawForeground() | QGraphicsScene::drawForeground() or QGraphicsView::drawForeground().
Q3Canvas::drawBackground() | QGraphicsScene::drawBackground() or QGraphicsView::drawBackground().

## Porting from Q3CanvasView

The equivalent of 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 provides new functionality. You can read more about this in QGraphicsView's documentation.

Q3CanvasView | QGraphicsView
--- | ---
Q3CanvasView::Q3CanvasView() | QGraphicsView provides the same constructors as Q3CanvasView, but without the name and flags arguments.
Q3CanvasView::canvas() | QGraphicsView::scene()
Q3CanvasView::inverseWorldMatrix() | QGraphicsView::matrix() and QMatrix::inverted(). See also QGraphicsView::mapToScene() and QGraphicsView::mapFromScene().
Q3CanvasView::setCanvas() | QGraphicsView::setScene()
Q3CanvasView::setWorldMatrix() | QGraphicsView::setMatrix(), QGraphicsView::rotate(), QGraphicsView::scale(), and more.
Q3CanvasView::worldMatrix() | QGraphicsView::matrix()
Q3CanvasView::drawContents() | QGraphicsView::render()

## Porting from Q3CanvasItem

The equivalent of 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.

Q3CanvasItem | QGraphicsItem
--- | ---
Q3CanvasItem::advance() | QGraphicsItem::advance(). See also QTimeLine and QGraphicsItemAnimation.
Q3CanvasItem::animated() | No equivalent; All items are advanced by QGraphicsScene::advance().
Q3CanvasItem::boundingRectAdvanced() | No equivalent. You can translate QGraphicsItem::boundingRect() instead (see QRectF::translate()).
Q3CanvasItem::canvas() | QGraphicsItem::scene()
Q3CanvasItem::collidesWith() | QGraphicsItem::collidesWithItem() and QGraphicsItem::collidesWithPath().
Q3CanvasItem::collisions() | QGraphicsItem::collidingItems()
Q3CanvasItem::draw() | QGraphicsItem::paint(). See also QStyleOptionGraphicsItem.
Q3CanvasItem::hide() | QGraphicsItem::hide() or QGraphicsItem::setVisible(). QGraphicsItems are visible by default; Q3CanvasItems, however, are not.
Q3CanvasItem::isActive() | No equivalent.
Q3CanvasItem::isVisible() | QGraphicsItem::isVisible(). QGraphicsItems are visible by default; Q3CanvasItems, however, are not.
Q3CanvasItem::move() | QGraphicsItem::setPos().
Q3CanvasItem::rtti() | QGraphicsItem::type() and qgraphicsitem_cast().
Q3CanvasItem::setActive() | No equivalent.
Q3CanvasItem::setAnimated() | No equivalent.
Q3CanvasItem::setCanvas() | QGraphicsScene::addItem().
Q3CanvasItem::setVelocity() | 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.
Q3CanvasItem::setVisible() | QGraphicsItem::setVisible(). QGraphicsItems are visible by default; Q3CanvasItems, however, are not.
Q3CanvasItem::setX() | QGraphicsItem::setPos()
Q3CanvasItem::setY() | QGraphicsItem::setPos()
Q3CanvasItem::setXVelocity() | No equivalent.
Q3CanvasItem::setYVelocity() | No equivalent.
Q3CanvasItem::setZ() | QGraphicsItem::setZValue()
Q3CanvasItem::show() | QGraphicsItem::show() or QGraphicsItem::setVisible(). QGraphicsItems are visible by default; Q3CanvasItems, however, are not.
Q3CanvasItem::xVelocity() | No equivalent.
Q3CanvasItem::yVelocity() | No equivalent.

### Q3CanvasPolygonalItem

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

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

Q3CanvasPolygonalItem | QAbstractGraphicsShapeItem
--- | ---
Q3CanvasPolygonalItem::areaPoints() | No equivalent; each item's geometry is stored in the respective subclass.
Q3CanvasPolygonalItem::areaPointsAdvanced() | No equivalent; you can use QPolygonF::translate() or QPainterPath::translate() instead.
Q3CanvasPolygonalItem::drawShape() | QGraphicsItem::paint(). You can set the pen and brush from inside this function.
Q3CanvasPolygonalItem::invalidate() | QGraphicsItem::prepareGeometryChange()
Q3CanvasPolygonalItem::isValid() | No equivalent; items' geometry is always in a valid state.
Q3CanvasPolygonalItem::winding() | This function is only useful for polygon items and path items; see QGraphicsPolygonItem::fillRule(), and QPainterPath::fillRule() for QGraphicsPathItem.

### Q3CanvasEllipse

The equivalent of 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:

     // Before
     Q3CanvasEllipse ellipse(10, 10);

     // After
     QGraphicsEllipseItem ellipse(-5, -5, 10, 10);

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

Q3CanvasEllipse | QGraphicsEllipseItem
--- | ---
Q3CanvasEllipse::angleLength() | QGraphicsEllipseItem::spanAngle()
Q3CanvasEllipse::angleStart() | QGraphicsEllipseItem::startAngle()
Q3CanvasEllipse::setAngles() | QGraphicsEllipseItem::setStartAngle() and QGraphicsEllipseItem::setSpanAngle()
Q3CanvasEllipse::setSize() | QGraphicsEllipseItem::setRect()

### Q3CanvasLine

The equivalent of Q3CanvasLine in Graphics View is called QGraphicsLineItem.

Q3CanvasLine | QGraphicsLineItem
--- | ---
Q3CanvasLine::endPoint() | QGraphicsLineItem::line() and QLineF::p2()
Q3CanvasLine::setPoints() | QGraphicsLineItem::setLine()
Q3CanvasLine::startPoint() | QGraphicsLineItem::line() and QLineF::p1()

### Q3CanvasPolygon

The equivalent of Q3CanvasPolygon in Graphics View is called QGraphicsPolygonItem.

Q3CanvasPolygon | QGraphicsPolygonItem
--- | ---
Q3CanvasPolygon::areaPoints() | QGraphicsPolygonItem::polygon() and QGraphicsItem::mapToParent()
Q3CanvasPolygon::points() | QGraphicsPolygonItem::polygon()
Q3CanvasPolygon::setPoints() | QGraphicsPolygonItem::setPolygon()

### Q3CanvasSpline

The equivalent of 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:

     static QPainterPath fromControlPoints(const Q3PointArray &pa)
     {
         QPainterPath path;
         path.moveTo(pa[0]);
         for (int i = 1; i < pa.size(); i += 3)
             path.cubicTo(pa[i], pa[(i + 1) % pa.size()], pa[(i + 2) % pa.size()]);
         return path;
     }

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

Q3CanvasSpline | QGraphicsPathItem
--- | ---
Q3CanvasSpline::closed() | No equivalent. You can call QPainterPath::closeSubPath() to close a subpath explicitly.

### Q3CanvasRectangle

The equivalent of Q3CanvasRectangle in Graphics View is called QGraphicsRectItem.

Q3CanvasRectangle | QGraphicsRectItem
--- | ---
Q3CanvasRectangle::height() | QGraphicsRectItem::rect() and QRectF::height()
Q3CanvasRectangle::setSize() | QGraphicsRectItem::setRect()
Q3CanvasRectangle::size() | QGraphicsRectItem::rect() and QRectF::size()
Q3CanvasRectangle::width() | QGraphicsRectItem::rect() and QRectF::width()
Q3CanvasRectangle::chunks() | No equivalent.

### 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 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().

#### 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:

             wildcardPath.replace("%1", "*");
             QFileInfo fi(wildcardPath);

             QList<QPixmap> frames;
             foreach (QString entry, QDir(fi.path(), fi.fileName()).entryList())
                 frames << QPixmap(fi.path() + "/" + entry);

### 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).

Q3CanvasText | QGraphicsSimpleTextItem
--- | ---
Q3CanvasText::color() | QGraphicsSimpleTextItem::pen().
Q3CanvasText::setColor() | QGraphicsSimpleTextItem::setPen().
Q3CanvasText::textFlags() | Use QGraphicsTextItem instead.

### Q3CanvasItemList

Use QList instead.