Редактирование: Porting to Qt 4.2's Graphics View

{{Категория:Qt_Издания}}
__NOTOC__

[[Категория:Qt_Издания]]

by Andreas Aardal Hanssen
<div class="introduction">
Graphics View is a new canvas framework for Qt 4. SupersedingQCanvas, Graphics View has lots of new features, including itemgrouping, item interaction through events, and floating-pointcoordinates. Still, Graphics View's design is similar to QCanvas's,ensuring that the transition to the new framework is as painless aspossible. In this article, we will port the "canvas" exampleincluded with Qt 3 to use Graphics View, demonstrating the portingprocess step by step.

*[[#makingtheexamplecompilewithqt4 | Making the Example Compile with Qt 4]]
*[[#portingfromqcanvastographicsview | Porting from QCanvas to Graphics View]]
*[[#compilingtheexampleagain | Compiling the Example Again]]
*[[#fixingthebehavior | Fixing the Behavior]]
*[[#conclusion | Conclusion]]
</div>
[[Image:qq21-portedcanvas.png|center]]

Qt 3's <tt>canvas</tt> example consists of about 1000 lines of code. Wewill start with the original sources from the Qt 3 source package andport it one step at a time. At the end of the process, we will havetwo applications that behave exactly the same, but each using adifferent set of classes and a different version of Qt.

<div id="makingtheexamplecompilewithqt4"></div>
===Making the Example Compile with Qt 4===


We start by making a copy of the <tt>examples/canvas</tt> directory fromQt 3. Then, using a command-line interpreter set up for Qt 4.2, werun the <tt>qt3to4</tt> porting tool on the example's <tt>canvas.pro</tt> file.This starts an automated in-place modification of the example, takingcare of the most tedious parts of porting an existing Qt 3application to Qt 4.
<source lang="cpp-qt">
$ qt3to4 canvas.pro
Using rules file: qt-4.2/tools/porting/src/q3porting.xml
Parsing...
Convert file tmp/canvas/canvas.cpp? (Y)es, (N)o, (A)ll A
Wrote to file: tmp/canvas/canvas.cpp
Wrote to file: tmp/canvas/main.cpp
Wrote to file: tmp/canvas/canvas.h
Wrote to file: tmp/canvas/canvas.pro
Writing log to portinglog.txt
</source> 
The <tt>qt3to4</tt> tool starts by asking whether or not it should convert<tt>canvas.cpp</tt>. Simply type '''A''' to tell it to port all files. Thetool generates a log file called <tt>portinglog.txt</tt> that shows allmodifications that were made.

The resulting program uses <tt>Q3Canvas</tt> and friends from the''Qt3Support'' library. We must make a few manual modificationsto make the example compile with Qt4.

In this article's code snippets, we follow the <tt>diff</tt> program'sconvention and use a leading plus sign (<tt>+</tt>) to indicate that a codeline is being added to the program. Similarly, a leading minus (<tt>-</tt>)identifies a line that must be removed.
<source lang="cpp-qt">
 #include <qapplication.h>
 #include <qimage.h>
+#include <QDesktopWidget>
</source> 
In <tt>main.cpp</tt>, we must include <tt><QDesktopWidget></tt>, as [[Qt:Документация_4.3.2/qdesktopwidget  | QDesktopWidget]] isreferenced indirectly from [http://www.crossplatform.ru/documentation/qtdoc4.3/qapplication.php#desktop QApplication::desktop()] at the end ofthe file. In Qt 3, this was not necessary because<tt>desktop()</tt> returned a plain [[Qt:Документация_4.3.2/qwidget  | QWidget]] pointer.

Two modifications are required in <tt>canvas.cpp</tt>:
<source lang="cpp-qt">
-  pixmap.convertFromImage(image, OrderedAlphaDither);
+  pixmap.convertFromImage(image, Qt::OrderedAlphaDither);

-  Main *m = new Main(canvas, 0, 0, WDestructiveClose);
+  Main *m = new Main(canvas, 0, 0, Qt::WDestructiveClose);
</source> 
In Qt 3, <tt>Qt</tt> was a class. Since most Qt classes derived directlyor indirectly from <tt>Qt</tt>, we could usually omit the <tt>Qt::</tt> prefix.

In Qt 4, <tt>Qt</tt> is a namespace, so we must either prefix every <tt>Qt</tt>member with the namespace name or add a <tt>using namespace Qt;</tt>directive at the beginning of our source files. The porting toolcatches most of these cases but not all of them.
<div id="portingfromqcanvastographicsview"></div>
===Porting from QCanvas to Graphics View===

At this point, the <tt>canvas</tt> example is a stand-alone Qt 4application that compiles and runs correctly. The only issue is thatwe rely on the ''Qt3Support'' library&emdash;more precisely on<tt>Q3Canvas</tt>. We have three options at our disposal:

*<br />'''We can call it a day.'''<br /><br />After all, linking against ''Qt3Support'' is not a crime.<br />
*<br />'''We can replace Q3Canvas with QtCanvas.'''<br /><br />The <tt>QtCanvas</tt> class is provided as a Qt Solution. Its purposeis to make it possible to use the old canvas frameworkavailable without linking in the entire ''Qt3Support'' library.<br />
*<br />'''We can port the application to Graphics View.'''<br /><br />Porting to Graphics View means that we have a more solid basis forfurther development. For example, if at a later point we want to additem grouping to the <tt>canvas</tt> example, we can build upon GraphicsView's grouping support.<br />

In the rest of this article we will see how to carry out the thirdoption. To help us in the process, we can consult the[http://doc.trolltech.comhttp://www.crossplatform.ru/qtdoc/graphicsview-porting.php Porting toGraphics View] page of the Qt online documentation.

Using the porting tables found there as a guide, we start byreplacing <tt>Q3Canvas</tt> and <tt>Q3CanvasView</tt> with[[Qt:Документация_4.3.2/qgraphicsscene  | QGraphicsScene]]and [[Qt:Документация_4.3.2/qgraphicsview  | QGraphicsView]] in all source files.We must also change the includes:
<source lang="cpp-qt">
-#include <q3canvas.h>
+#include <QGraphicsItem>
+#include <QGraphicsScene>
+#include <QGraphicsView>
</source> 
We also replace <tt>Q3CanvasItem</tt>s with their closest equivalents inGraphics View:

{| align="center" cellpadding="4" cellspacing="1" class="qqtable" width="40%"

|-
!Old Class
!New Class
|-
|Q3CanvasRectangle
|QGraphicsRectItem
|-
|Q3CanvasSpline
|QGraphicsPathItem
|-
|Q3CanvasSprite
|QGraphicsPixmapItem
|-
|Q3CanvasText
|QGraphicsSimpleTextItem
|}
Unsurprisingly, if we try to compile the example now, we get manyerrors and warnings.
<div id="compilingtheexampleagain"></div>
===Compiling the Example Again===

As a general rule when porting, it's a good idea to quickly bring theproject up to a state where it compiles again, even if it doesn'twork properly yet. Following this philosophy, the next step is tocomment out any block of code that references functions that don'texist in the new API. This includes incompatible constructors andsyntax errors. If a block of code accesses many functions that don'texist in the new API, we simply comment out the entire block.

For this example, commenting out all erroneous code is a five minuteoperation that quickly brings us to a point where the applicationcompiles again. This approach is very useful, as it allows us toport one component at a time, testing it as we go. Once the examplecompiles, we can run it and see what it looks like:

[[Image:qq21-canvasport1.png|center]]

The result isn't very exciting yet: All we have is a dysfunctionalmenu system and a gray canvas area.
<div id="fixingthebehavior"></div>
===Fixing the Behavior===

Let's start by fixing [[Qt:Документация_4.3.2/qgraphicsscene  | QGraphicsScene]]'sconstructor in <tt>main.cpp</tt>, so that the size of the canvas is back towhat it was in the original example:
<source lang="cpp-qt">
-  QGraphicsScene canvas; // (800, 600);
+  QGraphicsScene canvas(0, 0, 800, 600);
</source> 
Unlike <tt>Q3Canvas</tt>, [[Qt:Документация_4.3.2/qgraphicsscene  | QGraphicsScene]]lets us specify an arbitrary top-left corner for the scene. To obtain thesame behavior as before, we must explicitly pass (0, 0) to the constructor.
<source lang="cpp-qt">
FigureEditor::FigureEditor(QGraphicsScene &amp;c,
   QWidget *parent, const char *name, Qt::WFlags f)
-     // : QGraphicsView(&amp;c, parent, name, f)
+     : QGraphicsView(&amp;c, parent)
{
+  setObjectName(name);
+  setWindowFlags(name);
}
</source> 
In the <tt>FigureEditor</tt> constructor, we uncomment the base classinitialization, we remove the <tt>name</tt> and <tt>flags</tt> arguments from[[Qt:Документация_4.3.2/qgraphicsview  | QGraphicsView]]'s constructor, and insteadcall <tt>setObjectName()</tt> and <tt>setWindowFlags()</tt> explicitly.

If we compile and run the example now, it will look exactly like theoriginal example but without any items. This is a good indicationthat we are on the right track.

The next step is straightforward and quite fun to do: porting theitem classes one at a time. For most cases, it's just a matter ofdealing with code that we commented out ourselves. We will show howto port <tt>ImageItem</tt>, the base class for the butterfly and logoitems.
<source lang="cpp-qt">
class ImageItem : public QGraphicsRectItem
{
public:
	ImageItem(QImage img, QGraphicsScene *canvas);
-	int rtti() const { return imageRTTI; }
+	int type() const { return imageRTTI; }
bool hit(const QPoint &amp;) const;

protected:
-	void drawShape(QPainter &amp;);
+	void paint(QPainter *, const QStyleOptionGraphicsItem *,
+			   QWidget *);

private:
	QImage image;
	QPixmap pixmap;
};
</source> 
The <tt>rtti()</tt> virtual function in <tt>Q3CanvasItem</tt> is called<tt>type()</tt> in [[Qt:Документация_4.3.2/qgraphicsitem  | QGraphicsItem]], so wesimply rename it in the <tt>ImageItem</tt> subclass. Instead of<tt>drawShape()</tt>, we reimplement <tt>paint()</tt>, which plays the samerole but has a different signature.
<source lang="cpp-qt">
ImageItem::ImageItem(QImage img, QGraphicsScene *canvas)
-   // : QGraphicsRectItem(canvas), image(img)
+   : QGraphicsRectItem(0, canvas), image(img)
{
-	// setSize(image.width(), image.height());
+	setRect(0, 0, image.width(), image.height());
</source> 
Since Graphics View items can be created as children of other items,we must pass a null pointer as the parent to the[[Qt:Документация_4.3.2/qgraphicsrectitem  | QGraphicsRectItem]] constructor to createa top-level item. Also, there is no <tt>setSize()</tt> function in[[Qt:Документация_4.3.2/qgraphicsrectitem  | QGraphicsRectItem]]; instead,we call <tt>setRect()</tt> and pass (0, 0) as the top-left corner.
<source lang="cpp-qt">
-void ImageItem::drawShape(QPainter &amp;p)
+void ImageItem::paint(QPainter *p,
+                      const QStyleOptionGraphicsItem *,
+                      QWidget *)
{
#if defined(Q_WS_QWS)
-	p.drawImage(int(x()), int(y()), image, 0, 0, -1, -1,
-              Qt::OrderedAlphaDither);
+	p->drawImage(0, 0, image, 0, 0, -1, -1,
+               Qt::OrderedAlphaDither);
#else
-	p.drawPixmap(int(x()), int(y()), pixmap);
+	p->drawPixmap(0, 0, pixmap);
#endif
}
</source> 
We turn the <tt>drawShape()</tt> implementation into a <tt>paint()</tt>implementation. The tricky part here is that with Graphics View, the[[Qt:Документация_4.3.2/qpainter  | QPainter]] is set up so that we must draw inlocal coordinates. As a consequence, we call <tt>drawPixmap()</tt> with(0, 0) as the top-left corner.

If we compile and run the application now, we obtain logos andbutterflies stacked on top of each other in the windows's top-leftcorner:

[[Image:qq21-canvasport2.png|center]]

This shouldn't come as a surprise, considering that we've commentedout several code sections, including the item placement code in<tt>Main::addButterfly()</tt>, <tt>Main::addLogo()</tt>, etc. Let's start byfixing <tt>addButterfly()</tt>:
<source lang="cpp-qt">
   QAbstractGraphicsShapeItem *i =
          new ImageItem(butterflyimg[rand() % 4], &amp;canvas);
 -	// i->move(rand() % (canvas.width()
 -	//                   - butterflyimg->width()),
 -	//         rand() % (canvas.height()
 -	//                   - butterflyimg->height()));
 -	// i->setZ(rand() % 256 + 250);
 -  i->show();
 +	i->setPos(rand() % int(canvas.width()
 +                         - butterflyimg->width()),
 +            rand() % int(canvas.height()
 +                         - butterflyimg->height()));
 +  i->setZValue(rand() % 256 + 250);
</source> 
[http://www.crossplatform.ru/documentation/qtdoc4.3/qgraphicsitem.php#setPos QGraphicsItem::setPos()] does the sameas what <tt>move()</tt> did before, and <tt>setZ()</tt> is now called<tt>setZValue()</tt>. We also need a couple of <tt>int</tt> casts because[[Qt:Документация_4.3.2/qgraphicsscene  | QGraphicsScene]]'s <tt>width()</tt> and<tt>height()</tt> functions now return floating-point values and <tt>%</tt>is only defined for integers.

Notice that we don't need to call<tt>show()</tt> anymore, because Graphics View items are visible bydefault. Similar changes are required in <tt>addLogo()</tt>:
<source lang="cpp-qt">
QAbstractGraphicsShapeItem *i =
      new ImageItem(logoimg[rand() % 4], &amp;canvas);
-	// i->move(rand() % (canvas.width()
-	//                   - logoimg->width()),
-	//         rand() % (canvas.height()
-	//                   - logoimg->width()));
-	// i->setZ(rand() % 256 + 256);
-	i->show();
+	i->setPos(rand() % int(canvas.width()
+                         - logoimg->width()),
+            rand() % int(canvas.height()
+                         - logoimg->width()));
+	i->setZValue(rand() % 256 + 256);
</source> 
If we run the example now, all butterflies and logos are placedat random positions as we would expect. Our example is starting tolook more and more like the original. Next function: <tt>addSpline()</tt>.

For <tt>Q3CanvasSpline</tt>, the natural transition is to port to[[Qt:Документация_4.3.2/qgraphicspathitem  | QGraphicsPathItem]],which is based on [[Qt:Документация_4.3.2/qpainterpath  | QPainterPath]].[[Qt:Документация_4.3.2/qpainterpath  | QPainterPath]] supports curves, but itsinterface is different from that of <tt>Q3CanvasSpline</tt>, so some portingis required:
<source lang="cpp-qt">
-	// QGraphicsPathItem *i =
-	//       new QGraphicsPathItem(&amp;canvas);
+	QGraphicsPathItem *i =
+         new QGraphicsPathItem(0, &amp;canvas);

Q3PointArray pa(12);
pa[0] = QPoint(0, 0);
pa[1] = QPoint(size / 2, 0);
...
pa[11] = QPoint(-size / 2, 0);

-	i->setControlPoints(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()]);
+	i->setPath(path);
</source> 
Because [[Qt:Документация_4.3.2/qgraphicspathitem  | QGraphicsPathItem]] is a genericvector path item (not a spline item), we must build the curve shape manuallyusing [[Qt:Документация_4.3.2/qpainterpath  | QPainterPath]]'s <tt>moveTo()</tt> and<tt>cubicTo()</tt> functions instead of calling<tt>Q3CanvasSpline::setControlPoints()</tt>.

Porting the other items is straightforward, so let's skip ahead a bitand add some navigation support to the view instead. In<tt>Main::rotateClockwise()</tt>, we can replace three lines of code withone to get rotation support.
<source lang="cpp-qt">
void Main::rotateClockwise()
{
-	// QMatrix m = editor->worldMatrix();
-	// m.rotate(22.5);
-	// editor->setWorldMatrix(m);
+	editor->rotate(22.5);
}
</source> 
We can do similar changes to the other functions accessible throughthe '''View''' menu (<tt>zoomIn()</tt>, <tt>zoomOut()</tt>, etc.).In <tt>Main::paint()</tt>, we must reintroduce printing support:
<source lang="cpp-qt">
void Main::print()
{
	if (!printer) printer = new QPrinter;
	if (printer->setup(this)) {
		QPainter pp(printer);
-		// canvas.drawArea(QRect(0, 0, canvas.width(),
-		//                 canvas.height()),
-		//                 &amp;pp, FALSE);
+		canvas.render(&amp;pp);
	}
}
</source> 
The only change here is due to the differences in the signatures of<tt>Q3Canvas::drawArea()</tt> and [http://www.crossplatform.ru/documentation/qtdoc4.3/qgraphicsscene.php#render QGraphicsScene::render()]. It turns outwe can leave out most arguments to <tt>drawArea()</tt> because suitable defaultvalues are provided with the new API.

That's it! We now have a fully functional <tt>canvas</tt> example based onthe new Graphics View framework.
<div id="conclusion"></div>
===Conclusion===

As you can see from this article, moving from <tt>Q3Canvas</tt> toGraphics View is a fairly straightforward operation, once we'veunderstood the main differences between the two APIs.

There are a few pitfalls, though. Some <tt>Q3Canvas</tt> features thatwere targeted at 2D game programming, such as tiles and sprites, arenot directly supported in Graphics View; the "Porting to GraphicsView" page explains how to implement these features without too muchhassle. In addition, existing code that implicitly relied on integerprecision might still compile but behave differently with GraphicsView.

The complete source code for the ported <tt>canvas</tt> example isdistributed in Qt 4.2's <tt>examples/graphicsview/portedcanvas</tt>directory. Qt 4.2 also includes a <tt>portedasteroids</tt> example thatcorresponds to the Qt 3 <tt>asteroids</tt> example, which also used[[Qt:Документация 4.3.2//3.3/qcanvas.php | QCanvas]].

To conclude, I would like to wish you good luck with porting toGraphics View! If you run into trouble, let us know so we can helpand possibly improve the porting documentation.