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

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 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 Porting scenes with tiles for more information. The chunks-based indexing system has been replaced with an implicitly maintained internal BSP tree.

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 Printing

Porting scenes with tiles

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.

0

1

2

3

4

5

6

7

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:

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.

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.

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.

Q3CanvasSprite

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.