<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<!-- /home/gvatteka/dev/qt-4.3/doc/src/porting4-canvas.qdoc -->
<head>
<title>Porting to Graphics View</title>
<link href="classic.css" rel="stylesheet" type="text/css" />
</head>
<body>
<h1 align="center">Porting to Graphics View<br /><small></small></h1>
<a name="qgraphicsview-graphicsview-porting-graphics-canvas"></a><p>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, <a href="porting4.html#qcanvas"><tt>QCanvas</tt></a>. For more on Graphics View, see <a href="graphicsview.html">The Graphics View Framework</tt></a>.</p>
<p>This document walks through the steps needed, class by class and function by function, to port a <a href="porting4.html#qcanvas"><tt>QCanvas</tt></a> application to Graphics View.</p>
<ul><li><a href="#introduction">Introduction</a></li>
<li><a href="#porting-from-q3canvas">Porting from Q3Canvas</a></li>
<ul><li><a href="#porting-table">Porting table</a></li>
<li><a href="#porting-scenes-with-tiles">Porting scenes with tiles</a></li>
</ul>
<li><a href="#porting-from-q3canvasview">Porting from Q3CanvasView</a></li>
<ul><li><a href="#porting-table">Porting table</a></li>
<li><a href="#other-differences">Other differences</a></li>
</ul>
<li><a href="#porting-from-q3canvasitem">Porting from Q3CanvasItem</a></li>
<ul><li><a href="#q3canvaspolygonalitem">Q3CanvasPolygonalItem</a></li>
<li><a href="#q3canvasellipse">Q3CanvasEllipse</a></li>
<li><a href="#q3canvasline">Q3CanvasLine</a></li>
<li><a href="#q3canvaspolygon">Q3CanvasPolygon</a></li>
<li><a href="#q3canvasspline">Q3CanvasSpline</a></li>
<li><a href="#q3canvasrectangle">Q3CanvasRectangle</a></li>
<li><a href="#q3canvassprite">Q3CanvasSprite</a></li>
<ul><li><a href="#q3canvaspixmap-q3canvaspixmaparray">Q3CanvasPixmap, Q3CanvasPixmapArray</a></li>
</ul>
<li><a href="#q3canvastext">Q3CanvasText</a></li>
<li><a href="#q3canvasitemlist">Q3CanvasItemList</a></li>
</ul>
</ul>
<p>Qt 4.2 provides two complete examples of Q3Canvas applications ported to Graphics View:</p>
<ul>
<li>Ported Canvas Example</tt>, the canvas example from Qt 3.</li>
<li>Ported Asteroids Example</tt>, the Asteroids game from the Qt 3 demo.</li>
</ul>
<a name="introduction"></a>
<h3>Introduction</h3>
<p>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 <a href="porting4.html#qcanvas"><tt>QCanvas</tt></a> 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.</p>
<p>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 <a href="qt3to4.html#qt3to4"><tt>qt3to4</tt></a> tool on your project. This tool will automate the most tedious part of the porting effort.</p>
<p>Some additional steps are usually required before your application will compile and run. You can read more about the porting process in <a href="porting4.html">Porting to Qt 4</tt></a>.</p>
<a name="porting-from-q3canvas"></a>
<h3>Porting from Q3Canvas</h3>
<p><a href="gui/QGraphicsScene.html"><tt>QGraphicsScene</tt></a> is the closest equivalent to Q3Canvas. There are some noticable differences in this new API: Whereas the Q3Canvas classes use integer precision, <a href="gui/QGraphicsScene.html"><tt>QGraphicsScene</tt></a> is entirely based on double coordinates, with graphical primitives such as <a href="core/QPointF.html"><tt>QPointF</tt></a> instead of <a href="core/QPoint.html"><tt>QPoint</tt></a>, <a href="core/QRectF.html"><tt>QRectF</tt></a> instead of <a href="core/QRect.html"><tt>QRect</tt></a>, and <a href="gui/QPolygonF.html"><tt>QPolygonF</tt></a> and <a href="gui/QPainterPath.html"><tt>QPainterPath</tt></a>. The canvas area is defined by a scene rectangle, allowing negative coordinates, as opposed to Q3Canvas, which only defines a size (<a href="core/QSize.html"><tt>QSize</tt></a>), and whose top-left corner is always (0, 0).</p>
<p>In addition, there is no explicit support for canvas tiles anymore; see <a href="graphicsview-porting.html#porting-scenes-with-tiles">Porting scenes with tiles</tt></a> for more information. The chunks-based indexing system has been replaced with an implicitly maintained internal BSP tree.</p>
<a name="porting-table"></a>
<h4>Porting table</h4>
<p><table align="center" cellpadding="2" cellspacing="1" border="0">
<thead><tr valign="top" class="qt-style"><th>Q3Canvas</th><th><a href="gui/QGraphicsScene.html"><tt>QGraphicsScene</tt></a></th></tr></thead>
<tr valign="top" class="odd"><td>Q3Canvas::Q3Canvas()</td><td>There is no <a href="gui/QPixmap.html"><tt>QPixmap</tt></a> 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 <a href="gui/QGraphicsScene.html"><tt>QGraphicsScene</tt></a> subclass (see <a href="graphicsview-porting.html#porting-scenes-with-tiles">Porting scenes with tiles</tt></a>). In addition, the <a href="gui/QGraphicsScene.html"><tt>QGraphicsScene</tt></a> geometry is provided as a full <a href="core/QRectF.html"><tt>QRectF</tt></a>. Instead of Q3Canvas(int width, int height), you can use <a href="gui/QGraphicsScene.html"><tt>QGraphicsScene</tt></a>(int top, int left, int width, int height).</td></tr>
<tr valign="top" class="even"><td>Q3Canvas::allItems()</td><td>QGraphicsScene::items() returns a list of all items on the scene.</td></tr>
<tr valign="top" class="odd"><td>Q3Canvas::backgroundColor()</td><td>You can assign a color for the background through the QGraphicsScene::backgroundBrush or QGraphicsView::backgroundBrush properties.</td></tr>
<tr valign="top" class="even"><td>Q3Canvas::backgroundPixmap()</td><td>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().</td></tr>
<tr valign="top" class="odd"><td>Q3Canvas::chunkSize()</td><td>The closest equivalent to the chunks size in Q3Canvas is the depth of <a href="gui/QGraphicsScene.html"><tt>QGraphicsScene</tt></a>'s BSP tree. <a href="gui/QGraphicsScene.html"><tt>QGraphicsScene</tt></a> assigns a depth automatically, and the size of each scene segment depends on this depth, and QGraphicsScene::sceneRect(). See QGraphicsScene::itemIndexMethod.</td></tr>
<tr valign="top" class="even"><td>Q3Canvas::collisions()</td><td><a href="gui/QGraphicsScene.html"><tt>QGraphicsScene</tt></a> 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 (<a href="gui/QPainterPath.html"><tt>QPainterPath</tt></a>). You can also call QGraphicsScene::collidingItems() to determine collision with an item.</td></tr>
<tr valign="top" class="odd"><td>Q3Canvas::drawArea()</td><td>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 <a href="graphicsview.html#printing">Printing</tt></a></td></tr>
<tr valign="top" class="even"><td>Q3Canvas::onCanvas()</td><td>The is no equivalent to this function in Graphics View. However, you can combine QGraphicsScene::sceneRect() and QRectF::intersects():<pre> item->scene().sceneRect().intersects(item->sceneBoundingRect());
item->mapToScene(item->shape()).intersects(item->scene().sceneRect());</pre>
</td></tr>
<tr valign="top" class="odd"><td>Q3Canvas::rect()</td><td>The equivalent, QGraphicsScene::sceneRect(), returns a <a href="core/QRectF.html"><tt>QRectF</tt></a> (double precision coordinates). Its top-left corner can be an arbitrary coordinate (Q3Canvas::rect().topLeft() is always (0, 0)).</td></tr>
<tr valign="top" class="even"><td>Q3Canvas::resize()</td><td>You can call QGraphicsScene::setSceneRect(0, 0, width, height) instead.</td></tr>
<tr valign="top" class="odd"><td>Q3Canvas::retune()</td><td>See QGraphicsScene::itemIndexMethod. You can tune the indexing by setting a suitable sceneRect(). The optimal depth of <a href="gui/QGraphicsScene.html"><tt>QGraphicsScene</tt></a>'s BSP tree is determined automatically.</td></tr>
<tr valign="top" class="even"><td>Q3Canvas::setAdvancePeriod()</td><td>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 <a href="gui/QGraphicsItemAnimation.html"><tt>QGraphicsItemAnimation</tt></a>.</td></tr>
<tr valign="top" class="odd"><td>Q3Canvas::setAllChanged()</td><td>You can call QGraphicsScene::update() with no arguments.</td></tr>
<tr valign="top" class="even"><td>Q3Canvas::setChanged()</td><td>QGraphicsScene::update() will trigger a repaint of the whole scene, or parts of the scene.</td></tr>
<tr valign="top" class="odd"><td>Q3Canvas::setDoubleBuffering()</td><td>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 <a href="gui/QGraphicsScene.html"><tt>QGraphicsScene</tt></a>'s background through QGraphicsView::setCacheMode(). QGraphicsView::resetCachedContent() will reset the areas of the cache that has changed.</td></tr>
<tr valign="top" class="even"><td>Q3Canvas::tile()</td><td>See <a href="graphicsview-porting.html#porting-scenes-with-tiles">Porting scenes with tiles</tt></a>.</td></tr>
<tr valign="top" class="odd"><td>Q3Canvas::setTiles()</td><td>See <a href="graphicsview-porting.html#porting-scenes-with-tiles">Porting scenes with tiles</tt></a>.</td></tr>
<tr valign="top" class="even"><td>Q3Canvas::setUnchanged()</td><td>There is no equivalent in Graphics View. This call can usually be removed with no side effects.</td></tr>
<tr valign="top" class="odd"><td>Q3Canvas::setUpdatePeriod()</td><td>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 <a href="gui/QGraphicsItemAnimation.html"><tt>QGraphicsItemAnimation</tt></a>.</td></tr>
<tr valign="top" class="even"><td>Q3Canvas::size()</td><td><tt>QGraphicsScene::sceneRect().size()</tt> returns a <a href="core/QSizeF.html"><tt>QSizeF</tt></a>, with double precision coordinates.</td></tr>
<tr valign="top" class="odd"><td>Q3Canvas::validChunk()</td><td>To determine if an area is inside the scene area or not, you can combine QRectF::intersects() with QGraphicsScene::sceneRect().</td></tr>
<tr valign="top" class="even"><td>Q3Canvas::resized()</td><td><a href="gui/QGraphicsScene.html"><tt>QGraphicsScene</tt></a> emits sceneRectChanged() whenever the scene rect changes.</td></tr>
<tr valign="top" class="odd"><td>Q3Canvas::drawBackground()</td><td>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.</td></tr>
<tr valign="top" class="even"><td>Q3Canvas::drawForeground()</td><td>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.</td></tr>
</table></p>
<a name="porting-scenes-with-tiles"></a>
<h4>Porting scenes with tiles</h4>
<p><a href="gui/QGraphicsScene.html"><tt>QGraphicsScene</tt></a> does not provide an API for tiles. However, you can achieve similar behavior by drawing pixmaps in a reimplementation of QGraphicsScene::drawBackground().</p>
<p>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.</p>
<p><table align="center" cellpadding="2" cellspacing="1" border="0">
<tr valign="top" class="odd"><td>0</td><td>1</td><td>2</td><td>3</td></tr>
<tr valign="top" class="even"><td>4</td><td>5</td><td>6</td><td>7</td></tr>
</table></p>
<p>With Graphics View, this pixmap can be stored as a member of a subclass of <a href="gui/QGraphicsScene.html"><tt>QGraphicsScene</tt></a>. 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:</p>
<pre> class TileScene : public QGraphicsScene
{
public:
...
void setTiles(const QPixmap &pixmap, int h, int v,
int tileHeight, int tileWidth);
void setTile(int x, int y, int tilenum);
private:
QRect tileRect(int x, int y) const;
QRect tileRect(int tileNum) const;
QVector<QVector<int> > tiles;
QPixmap tilePixmap;
int tileW, tileH;
int hTiles, vTiles;
};</pre>
<p>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.</p>
<p>We start by creating a subclass of <a href="gui/QGraphicsScene.html"><tt>QGraphicsScene</tt></a> ("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.</p>
<pre> void TileScene::setTiles(const QPixmap &pixmap, int h, int v,
int tileHeight, int tileWidth)
{
tilePixmap = pixmap;
tileW = tileWidth;
tileH = tileHeight;
hTiles = h;
vTiles = v;
tiles.resize(v);
for (int y = 0; y < v; ++y)
tiles[y].resize(h);
}</pre>
<p>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.</p>
<pre> void TileScene::setTile(int x, int y, int tilenum)
{
tiles[y][x] = tilenum;
update(tileRect(x, y));
}</pre>
<p>The setTile() function updates the tiles index, and then updates the corresponding rect in the scene by calling tileRect().</p>
<pre> QRect TileScene::tileRect(int x, int y) const
{
return QRect(x * tileW, y * tileH, tileW, tileH);
}</pre>
<p>The first tileRect() function returns a <a href="core/QRect.html"><tt>QRect</tt></a> for the tile at position (x, y).</p>
<pre> QRect TileScene::tileRect(int tileNum) const
{
int numHTiles = tilePixmap.width() / tileW;
int numVTiles = tilePixmap.height() / tileH;
return tileRect(tileNum % numHTiles, tileNum / numHTiles);
}</pre>
<p>The second tileRect() function returns a <a href="core/QRect.html"><tt>QRect</tt></a> for a tile number. With these functions in place, we can implement the drawBackground() function.</p>
<pre> void drawBackground(QPainter *painter, const QRectF &exposed)
{
for (int y = 0; y < vTiles; ++y) {
for (int x = 0; x < hTiles; ++x) {
QRect destRect = tileRect(x, y);
if (exposed.intersects(destRect)) {
painter->drawPixmap(destRect, tilePixmap,
tileRect(tiles[y][x]));
}
}
}
}</pre>
<p>In drawBackground(), we redraw all tiles that have been exposed by intersecting each tile rect with the exposed background area.</p>
<a name="porting-from-q3canvasview"></a>
<h3>Porting from Q3CanvasView</h3>
<p>The closest equivalent to Q3CanvasView in Graphics View is called <a href="gui/QGraphicsView.html"><tt>QGraphicsView</tt></a>. In most cases, this is the easiest class to port. In addition to providing all of Q3CanvasView's functionality, <a href="gui/QGraphicsView.html"><tt>QGraphicsView</tt></a> includes some useful new features. You can read more about this in <a href="gui/QGraphicsView.html"><tt>QGraphicsView</tt></a>'s documentation.</p>
<a name="porting-table"></a>
<h4>Porting table</h4>
<p><table align="center" cellpadding="2" cellspacing="1" border="0">
<thead><tr valign="top" class="qt-style"><th>Q3CanvasView</th><th><a href="gui/QGraphicsView.html"><tt>QGraphicsView</tt></a></th></tr></thead>
<tr valign="top" class="odd"><td>Q3CanvasView::Q3CanvasView()</td><td><a href="gui/QGraphicsView.html"><tt>QGraphicsView</tt></a> provides the same constructors as Q3CanvasView, but without the name and flags arguments. You can set the name by calling setObjectName(), and the flags by calling setWindowFlags().</td></tr>
<tr valign="top" class="even"><td>Q3CanvasView::canvas()</td><td>QGraphicsView::scene() returns the scene that is currently associated with the view. <a href="gui/QGraphicsScene.html"><tt>QGraphicsScene</tt></a> also provides the opposite function, QGraphicsScene::views(), which returns a list of views observing the scene.</td></tr>
<tr valign="top" class="odd"><td>Q3CanvasView::inverseWorldMatrix()</td><td>You can call QGraphicsView::matrix() and QMatrix::inverted(). QGraphicsView::mapToScene() and QGraphicsView::mapFromScene() allow transforming of viewport shapes to scene shapes, and vice versa.</td></tr>
<tr valign="top" class="even"><td>Q3CanvasView::setCanvas()</td><td>QGraphicsView::setScene().</td></tr>
<tr valign="top" class="odd"><td>Q3CanvasView::setWorldMatrix()</td><td>QGraphicsView::setMatrix(), QGraphicsView::rotate(), QGraphicsView::scale(), QGraphicsView::shear() and QGraphicsView::translate().</td></tr>
<tr valign="top" class="even"><td>Q3CanvasView::worldMatrix()</td><td>QGraphicsView::matrix()</td></tr>
<tr valign="top" class="odd"><td>Q3CanvasView::drawContents()</td><td>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 <a href="gui/QGraphicsScene.html"><tt>QGraphicsScene</tt></a>.</td></tr>
</table></p>
<a name="other-differences"></a>
<h4>Other differences</h4>
<p><a href="gui/QGraphicsView.html"><tt>QGraphicsView</tt></a> 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.</p>
<p>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, <a href="gui/QGraphicsView.html"><tt>QGraphicsView</tt></a> will provide rubber band selection or click-and-pull navigation using the OpenHandCursor and ClosedHandCursor cursors.</p>
<a name="porting-from-q3canvasitem"></a>
<h3>Porting from Q3CanvasItem</h3>
<p>The closest equivalent to Q3CanvasItem in Graphics View is called <a href="gui/QGraphicsItem.html"><tt>QGraphicsItem</tt></a>. Deriving from this class is very common, and because of that, porting from Q3CanvasItem often involves more work than Q3Canvas and Q3CanvasView.</p>
<p>Q3CanvasItem has become easier to use, easier to subclass, and more powerful with <a href="gui/QGraphicsItem.html"><tt>QGraphicsItem</tt></a>. 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 <a href="gui/QGraphicsItem.html"><tt>QGraphicsItem</tt></a> in its own class documentation.</p>
<p>This section starts with a table that shows how to port each function from Q3CanvasItem to <a href="gui/QGraphicsItem.html"><tt>QGraphicsItem</tt></a>. Immediately after that, each of Q3CanvasItem's standard subclasses have a section of their own.</p>
<p><table align="center" cellpadding="2" cellspacing="1" border="0">
<thead><tr valign="top" class="qt-style"><th>Q3CanvasItem</th><th><a href="gui/QGraphicsItem.html"><tt>QGraphicsItem</tt></a></th></tr></thead>
<tr valign="top" class="odd"><td>Q3CanvasItem::advance()</td><td>QGraphicsItem::advance() is provided for compatibility. QGraphicsScene::advance() calls QGraphicsItem::advance() for all items. See also <a href="core/QTimeLine.html"><tt>QTimeLine</tt></a> and <a href="gui/QGraphicsItemAnimation.html"><tt>QGraphicsItemAnimation</tt></a>.</td></tr>
<tr valign="top" class="even"><td>Q3CanvasItem::animated()</td><td>No equivalent; all items are advanced by QGraphicsScene::advance().</td></tr>
<tr valign="top" class="odd"><td>Q3CanvasItem::boundingRectAdvanced()</td><td>No equivalent. You can translate QGraphicsItem::boundingRect() instead (see QRectF::translate()).</td></tr>
<tr valign="top" class="even"><td>Q3CanvasItem::canvas()</td><td>QGraphicsItem::scene()</td></tr>
<tr valign="top" class="odd"><td>Q3CanvasItem::collidesWith()</td><td>QGraphicsItem::collidesWithItem() and QGraphicsItem::collidesWithPath().</td></tr>
<tr valign="top" class="even"><td>Q3CanvasItem::collisions()</td><td>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.</td></tr>
<tr valign="top" class="odd"><td>Q3CanvasItem::draw()</td><td>QGraphicsItem::paint(). See also <a href="gui/QStyleOptionGraphicsItem.html"><tt>QStyleOptionGraphicsItem</tt></a>, QGraphicsScene::drawItems() and QGraphicsView::drawItems().</td></tr>
<tr valign="top" class="even"><td>Q3CanvasItem::hide()</td><td>QGraphicsItem::hide() or QGraphicsItem::setVisible(). <a href="gui/QGraphicsItem.html"><tt>QGraphicsItem</tt></a>s are <i>visible</i> by default; <tt>Q3CanvasItem</tt>s, however, are not.</td></tr>
<tr valign="top" class="odd"><td>Q3CanvasItem::isActive()</td><td>No equivalent. To achieve similar behavior, you can add this property in a custom subclass of <a href="gui/QGraphicsItem.html"><tt>QGraphicsItem</tt></a>.</td></tr>
<tr valign="top" class="even"><td>Q3CanvasItem::isVisible()</td><td>QGraphicsItem::isVisible(). <a href="gui/QGraphicsItem.html"><tt>QGraphicsItem</tt></a>s are <i>visible</i> by default; <tt>Q3CanvasItem</tt>s, however, are not.</td></tr>
<tr valign="top" class="odd"><td>Q3CanvasItem::move()</td><td>You can call QGraphicsItem::setPos() to change the position of the item.</td></tr>
<tr valign="top" class="even"><td>Q3CanvasItem::rtti()</td><td>QGraphicsItem::type() and qgraphicsitem_cast().</td></tr>
<tr valign="top" class="odd"><td>Q3CanvasItem::setActive()</td><td>No equivalent.</td></tr>
<tr valign="top" class="even"><td>Q3CanvasItem::setAnimated()</td><td>No equivalent; all items are by default "animated" (i.e., QGraphicsScene::advance() advances all items on the scene).</td></tr>
<tr valign="top" class="odd"><td>Q3CanvasItem::setCanvas()</td><td>You can call QGraphicsScene::addItem(), or pass a pointer to the canvas to <a href="gui/QGraphicsItem.html"><tt>QGraphicsItem</tt></a>'s constructor.</td></tr>
<tr valign="top" class="even"><td>Q3CanvasItem::setVelocity()</td><td>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 <a href="core/QTimeLine.html"><tt>QTimeLine</tt></a> and <a href="gui/QGraphicsItemAnimation.html"><tt>QGraphicsItemAnimation</tt></a>.</td></tr>
<tr valign="top" class="odd"><td>Q3CanvasItem::setVisible()</td><td>QGraphicsItem::setVisible(). <a href="gui/QGraphicsItem.html"><tt>QGraphicsItem</tt></a>s are <i>visible</i> by default; <tt>Q3CanvasItem</tt>s, however, are not.</td></tr>
<tr valign="top" class="even"><td>Q3CanvasItem::setX()</td><td>QGraphicsItem::setPos()</td></tr>
<tr valign="top" class="odd"><td>Q3CanvasItem::setY()</td><td>QGraphicsItem::setPos()</td></tr>
<tr valign="top" class="even"><td>Q3CanvasItem::setXVelocity()</td><td>No equivalent.</td></tr>
<tr valign="top" class="odd"><td>Q3CanvasItem::setYVelocity()</td><td>No equivalent.</td></tr>
<tr valign="top" class="even"><td>Q3CanvasItem::setZ()</td><td>QGraphicsItem::setZValue()</td></tr>
<tr valign="top" class="odd"><td>Q3CanvasItem::show()</td><td>QGraphicsItem::show() or QGraphicsItem::setVisible(). <a href="gui/QGraphicsItem.html"><tt>QGraphicsItem</tt></a>s are <i>visible</i> by default; <tt>Q3CanvasItem</tt>s, however, are not.</td></tr>
<tr valign="top" class="even"><td>Q3CanvasItem::xVelocity()</td><td>No equivalent.</td></tr>
<tr valign="top" class="odd"><td>Q3CanvasItem::yVelocity()</td><td>No equivalent.</td></tr>
</table></p>
<a name="q3canvaspolygonalitem"></a>
<h4>Q3CanvasPolygonalItem</h4>
<p>The closest equivalent to <a href="graphicsview-porting.html#q3canvaspolygonalitem"><tt>Q3CanvasPolygonalItem</tt></a> in Graphics View is called <a href="gui/QAbstractGraphicsShapeItem.html"><tt>QAbstractGraphicsShapeItem</tt></a>. Unlike <a href="graphicsview-porting.html#q3canvaspolygonalitem"><tt>Q3CanvasPolygonalItem</tt></a>, it does not define area points (Q3CanvasPolygonalItem::areaPoints()); instead, each item's geometry is stored as a member of the subclasses.</p>
<p>The Q3CanvasPolygonalItem::drawShape() function is no longer available; instead, you can set the brush and pen from inside QGraphicsItem::paint().</p>
<p><table align="center" cellpadding="2" cellspacing="1" border="0">
<thead><tr valign="top" class="qt-style"><th><a href="graphicsview-porting.html#q3canvaspolygonalitem"><tt>Q3CanvasPolygonalItem</tt></a></th><th><a href="gui/QAbstractGraphicsShapeItem.html"><tt>QAbstractGraphicsShapeItem</tt></a></th></tr></thead>
<tr valign="top" class="odd"><td>Q3CanvasPolygonalItem::areaPoints()</td><td>No equivalent; each item's geometry is stored in the respective subclass.</td></tr>
<tr valign="top" class="even"><td>Q3CanvasPolygonalItem::areaPointsAdvanced()</td><td>No equivalent; you can use QPolygonF::translate() or QPainterPath::translate() instead.</td></tr>
<tr valign="top" class="odd"><td>Q3CanvasPolygonalItem::drawShape()</td><td>QGraphicsItem::paint(). You can set the pen and brush from inside this function.</td></tr>
<tr valign="top" class="even"><td>Q3CanvasPolygonalItem::invalidate()</td><td>Call QGraphicsItem::prepareGeometryChange() before changing the item's geometry.</td></tr>
<tr valign="top" class="odd"><td>Q3CanvasPolygonalItem::isValid()</td><td>No equivalent; items' geometry is always in a valid state.</td></tr>
<tr valign="top" class="even"><td>Q3CanvasPolygonalItem::winding()</td><td>This function is only useful for polygon items and path items; see QGraphicsPolygonItem::fillRule(), and QPainterPath::fillRule() for <a href="gui/QGraphicsPathItem.html"><tt>QGraphicsPathItem</tt></a>.</td></tr>
</table></p>
<a name="q3canvasellipse"></a>
<h4>Q3CanvasEllipse</h4>
<p>The closest equivalent to <a href="graphicsview-porting.html#q3canvasellipse"><tt>Q3CanvasEllipse</tt></a> in Graphics View is called <a href="gui/QGraphicsEllipseItem.html"><tt>QGraphicsEllipseItem</tt></a>. The most noticable difference to <a href="gui/QGraphicsEllipseItem.html"><tt>QGraphicsEllipseItem</tt></a> is that the ellipse is not longer drawn centered around its position; rather, it is drawn using a bounding <a href="core/QRectF.html"><tt>QRectF</tt></a>, just like QPainter::drawEllipse().</p>
<p>For compatibility, you may want to shift the ellipse up and to the left to keep the ellipse centered. Example:</p>
<pre> <span class="comment">// Before</span>
Q3CanvasEllipse ellipse(10, 10);
<span class="comment">// After</span>
QGraphicsEllipseItem ellipse(-5, -5, 10, 10);</pre>
<p>Note: <a href="gui/QGraphicsEllipseItem.html"><tt>QGraphicsEllipseItem</tt></a> uses QAbstractGraphicsShapeItem::pen() for outlines, whereas <a href="graphicsview-porting.html#q3canvasellipse"><tt>Q3CanvasEllipse</tt></a> did not use Q3CanvasPolygonalItem::pen().</p>
<p><table align="center" cellpadding="2" cellspacing="1" border="0">
<thead><tr valign="top" class="qt-style"><th><a href="graphicsview-porting.html#q3canvasellipse"><tt>Q3CanvasEllipse</tt></a></th><th><a href="gui/QGraphicsEllipseItem.html"><tt>QGraphicsEllipseItem</tt></a></th></tr></thead>
<tr valign="top" class="odd"><td>Q3CanvasEllipse::angleLength()</td><td>QGraphicsEllipseItem::spanAngle()</td></tr>
<tr valign="top" class="even"><td>Q3CanvasEllipse::angleStart()</td><td>QGraphicsEllipseItem::startAngle()</td></tr>
<tr valign="top" class="odd"><td>Q3CanvasEllipse::setAngles()</td><td>QGraphicsEllipseItem::setStartAngle() and QGraphicsEllipseItem::setSpanAngle()</td></tr>
<tr valign="top" class="even"><td>Q3CanvasEllipse::setSize()</td><td>QGraphicsEllipseItem::setRect()</td></tr>
</table></p>
<a name="q3canvasline"></a>
<h4>Q3CanvasLine</h4>
<p>The closest equivalent to <a href="graphicsview-porting.html#q3canvasline"><tt>Q3CanvasLine</tt></a> in Graphics View is called <a href="gui/QGraphicsLineItem.html"><tt>QGraphicsLineItem</tt></a>.</p>
<p><table align="center" cellpadding="2" cellspacing="1" border="0">
<thead><tr valign="top" class="qt-style"><th><a href="graphicsview-porting.html#q3canvasline"><tt>Q3CanvasLine</tt></a></th><th><a href="gui/QGraphicsLineItem.html"><tt>QGraphicsLineItem</tt></a></th></tr></thead>
<tr valign="top" class="odd"><td>Q3CanvasLine::endPoint()</td><td>QGraphicsLineItem::line() and QLineF::p2()</td></tr>
<tr valign="top" class="even"><td>Q3CanvasLine::setPoints()</td><td>QGraphicsLineItem::setLine()</td></tr>
<tr valign="top" class="odd"><td>Q3CanvasLine::startPoint()</td><td>QGraphicsLineItem::line() and QLineF::p1()</td></tr>
</table></p>
<a name="q3canvaspolygon"></a>
<h4>Q3CanvasPolygon</h4>
<p>The closest equivalent to <a href="graphicsview-porting.html#q3canvaspolygon"><tt>Q3CanvasPolygon</tt></a> in Graphics View is called <a href="gui/QGraphicsPolygonItem.html"><tt>QGraphicsPolygonItem</tt></a>.</p>
<p><table align="center" cellpadding="2" cellspacing="1" border="0">
<thead><tr valign="top" class="qt-style"><th><a href="graphicsview-porting.html#q3canvaspolygon"><tt>Q3CanvasPolygon</tt></a></th><th><a href="gui/QGraphicsPolygonItem.html"><tt>QGraphicsPolygonItem</tt></a></th></tr></thead>
<tr valign="top" class="odd"><td>Q3CanvasPolygon::areaPoints()</td><td>QGraphicsPolygonItem::polygon() and QGraphicsItem::mapToParent()</td></tr>
<tr valign="top" class="even"><td>Q3CanvasPolygon::points()</td><td>QGraphicsPolygonItem::polygon()</td></tr>
<tr valign="top" class="odd"><td>Q3CanvasPolygon::setPoints()</td><td>QGraphicsPolygonItem::setPolygon()</td></tr>
</table></p>
<a name="q3canvasspline"></a>
<h4>Q3CanvasSpline</h4>
<p>The closest equivalent to <a href="graphicsview-porting.html#q3canvasspline"><tt>Q3CanvasSpline</tt></a> in Graphics View is called <a href="gui/QGraphicsPathItem.html"><tt>QGraphicsPathItem</tt></a>. This item can be used to describe any type of path supported by <a href="gui/QPainter.html"><tt>QPainter</tt></a>.</p>
<p><a href="graphicsview-porting.html#q3canvasspline"><tt>Q3CanvasSpline</tt></a> takes its control points as a Q3PointArray, but <a href="gui/QPainterPath.html"><tt>QPainterPath</tt></a> operates on a sequence of calls to QPainterPath::moveTo() and QPainterPath::cubicTo(). Here is how you can convert a bezier curve Q3PointArray to a <a href="gui/QPainterPath.html"><tt>QPainterPath</tt></a>:</p>
<pre> 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;
}</pre>
<p>Note: <a href="gui/QGraphicsPathItem.html"><tt>QGraphicsPathItem</tt></a> uses QAbstractGraphicsShapeItem::pen() for outlines, whereas <a href="graphicsview-porting.html#q3canvasspline"><tt>Q3CanvasSpline</tt></a> did not use Q3CanvasPolygonalItem::pen().</p>
<p><table align="center" cellpadding="2" cellspacing="1" border="0">
<thead><tr valign="top" class="qt-style"><th><a href="graphicsview-porting.html#q3canvasspline"><tt>Q3CanvasSpline</tt></a></th><th><a href="gui/QGraphicsPathItem.html"><tt>QGraphicsPathItem</tt></a></th></tr></thead>
<tr valign="top" class="odd"><td>Q3CanvasSpline::closed()</td><td>No equivalent. You can call QPainterPath::closeSubPath() to close a subpath explicitly.</td></tr>
</table></p>
<a name="q3canvasrectangle"></a>
<h4>Q3CanvasRectangle</h4>
<p>The closest equivalent to <a href="graphicsview-porting.html#q3canvasrectangle"><tt>Q3CanvasRectangle</tt></a> in Graphics View is called <a href="gui/QGraphicsRectItem.html"><tt>QGraphicsRectItem</tt></a>.</p>
<p><table align="center" cellpadding="2" cellspacing="1" border="0">
<thead><tr valign="top" class="qt-style"><th><a href="graphicsview-porting.html#q3canvasrectangle"><tt>Q3CanvasRectangle</tt></a></th><th><a href="gui/QGraphicsRectItem.html"><tt>QGraphicsRectItem</tt></a></th></tr></thead>
<tr valign="top" class="odd"><td>Q3CanvasRectangle::height()</td><td>QGraphicsRectItem::rect() and QRectF::height()</td></tr>
<tr valign="top" class="even"><td>Q3CanvasRectangle::setSize()</td><td>QGraphicsRectItem::setRect()</td></tr>
<tr valign="top" class="odd"><td>Q3CanvasRectangle::size()</td><td>QGraphicsRectItem::rect() and QRectF::size()</td></tr>
<tr valign="top" class="even"><td>Q3CanvasRectangle::width()</td><td>QGraphicsRectItem::rect() and QRectF::width()</td></tr>
<tr valign="top" class="odd"><td>Q3CanvasRectangle::chunks()</td><td>No equivalent.</td></tr>
</table></p>
<a name="q3canvassprite"></a>
<h4>Q3CanvasSprite</h4>
<p><a href="graphicsview-porting.html#q3canvassprite"><tt>Q3CanvasSprite</tt></a> is the item class that differs the most from its Q3Canvas predecessor. The closest resemblance of <a href="graphicsview-porting.html#q3canvassprite"><tt>Q3CanvasSprite</tt></a> in Graphics View is <a href="gui/QGraphicsPixmapItem.html"><tt>QGraphicsPixmapItem</tt></a>.</p>
<p><a href="graphicsview-porting.html#q3canvassprite"><tt>Q3CanvasSprite</tt></a> supports animated pixmaps; <a href="gui/QGraphicsPixmapItem.html"><tt>QGraphicsPixmapItem</tt></a>, 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.</p>
<p>For the Ported Asteroids Example</tt>, a subclass of <a href="gui/QGraphicsPixmapItem.html"><tt>QGraphicsPixmapItem</tt></a> is used to replace <a href="graphicsview-porting.html#q3canvassprite"><tt>Q3CanvasSprite</tt></a>, storing a list of pixmaps and a frame counter. The animation is advanced in QGraphicsItem::advance().</p>
<a name="q3canvaspixmap-q3canvaspixmaparray"></a>
<h5>Q3CanvasPixmap, Q3CanvasPixmapArray</h5>
<p>These classes have been removed from the API. You can use <a href="gui/QPixmap.html"><tt>QPixmap</tt></a> instead of Q3CanvasPixmap, and QList instead of Q3CanvasPixmapArray.</p>
<p>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 <a href="core/QDir.html"><tt>QDir</tt></a>:</p>
<pre> wildcardPath.replace("%1", "*");
QFileInfo fi(wildcardPath);
QList<QPixmap> frames;
foreach (QString entry, QDir(fi.path(), fi.fileName()).entryList())
frames << QPixmap(fi.path() + "/" + entry);</pre>
<a name="q3canvastext"></a>
<h4>Q3CanvasText</h4>
<p><a href="graphicsview-porting.html#q3canvastext"><tt>Q3CanvasText</tt></a> has been split into two classes in Graphics View: <a href="gui/QGraphicsSimpleTextItem.html"><tt>QGraphicsSimpleTextItem</tt></a> and <a href="gui/QGraphicsTextItem.html"><tt>QGraphicsTextItem</tt></a>. For porting, <a href="gui/QGraphicsSimpleTextItem.html"><tt>QGraphicsSimpleTextItem</tt></a> should be adequate. <a href="gui/QGraphicsTextItem.html"><tt>QGraphicsTextItem</tt></a> provides advanced document structuring features similar to that of <a href="gui/QTextEdit.html"><tt>QTextEdit</tt></a>, and it also allows interaction (e.g., editing and selection).</p>
<p><table align="center" cellpadding="2" cellspacing="1" border="0">
<thead><tr valign="top" class="qt-style"><th><a href="graphicsview-porting.html#q3canvastext"><tt>Q3CanvasText</tt></a></th><th><a href="gui/QGraphicsSimpleTextItem.html"><tt>QGraphicsSimpleTextItem</tt></a></th></tr></thead>
<tr valign="top" class="odd"><td>Q3CanvasText::color()</td><td>QGraphicsSimpleTextItem::pen().</td></tr>
<tr valign="top" class="even"><td>Q3CanvasText::setColor()</td><td>QGraphicsSimpleTextItem::setPen().</td></tr>
<tr valign="top" class="odd"><td>Q3CanvasText::textFlags()</td><td>Use <a href="gui/QGraphicsTextItem.html"><tt>QGraphicsTextItem</tt></a> instead.</td></tr>
</table></p>
<a name="q3canvasitemlist"></a>
<h4>Q3CanvasItemList</h4>
<p>Use QList instead.</p>
<p /><address><hr /><div align="center">
<table width="100%" cellspacing="0" border="0"><tr class="address">
<td width="30%">Copyright © 2007 <a href="trolltech.html">Trolltech</a></td>
<td width="40%" align="center"><a href="trademarks.html">Trademarks</a></td>
<td width="30%" align="right"><div align="right">Qt Jambi </div></td>
</tr></table></div></address></body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
a6711891ce757817bba854bf3f25205a
>
files
>
337
