<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- plugandpaint.qdoc -->
<title>Qt 4.8: Plug & Paint Basic Tools Example</title>
<link rel="stylesheet" type="text/css" href="style/style.css" />
<script src="scripts/jquery.js" type="text/javascript"></script>
<script src="scripts/functions.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="style/superfish.css" />
<link rel="stylesheet" type="text/css" href="style/narrow.css" />
<!--[if IE]>
<meta name="MSSmartTagsPreventParsing" content="true">
<meta http-equiv="imagetoolbar" content="no">
<![endif]-->
<!--[if lt IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie6.css">
<![endif]-->
<!--[if IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie7.css">
<![endif]-->
<!--[if IE 8]>
<link rel="stylesheet" type="text/css" href="style/style_ie8.css">
<![endif]-->
<script src="scripts/superfish.js" type="text/javascript"></script>
<script src="scripts/narrow.js" type="text/javascript"></script>
</head>
<body class="" onload="CheckEmptyAndLoadList();">
<div class="header" id="qtdocheader">
<div class="content">
<div id="nav-logo">
<a href="index.html">Home</a></div>
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
<div id="narrowsearch"></div>
<div id="nav-topright">
<ul>
<li class="nav-topright-home"><a href="http://qt.digia.com/">Qt HOME</a></li>
<li class="nav-topright-dev"><a href="http://qt-project.org/">DEV</a></li>
<li class="nav-topright-doc nav-topright-doc-active"><a href="http://qt-project.org/doc/">
DOC</a></li>
<li class="nav-topright-blog"><a href="http://blog.qt.digia.com/">BLOG</a></li>
</ul>
</div>
<div id="shortCut">
<ul>
<li class="shortCut-topleft-inactive"><span><a href="index.html">Qt 4.8</a></span></li>
<li class="shortCut-topleft-active"><a href="http://qt-project.org/doc/">ALL VERSIONS </a></li>
</ul>
</div>
<ul class="sf-menu" id="narrowmenu">
<li><a href="#">API Lookup</a>
<ul>
<li><a href="classes.html">Class index</a></li>
<li><a href="functions.html">Function index</a></li>
<li><a href="modules.html">Modules</a></li>
<li><a href="namespaces.html">Namespaces</a></li>
<li><a href="qtglobal.html">Global Declarations</a></li>
<li><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</li>
<li><a href="#">Qt Topics</a>
<ul>
<li><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li><a href="supported-platforms.html">Supported Platforms</a></li>
<li><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</li>
<li><a href="#">Examples</a>
<ul>
<li><a href="all-examples.html">Examples</a></li>
<li><a href="tutorials.html">Tutorials</a></li>
<li><a href="demos.html">Demos</a></li>
<li><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="wrapper">
<div class="hd">
<span></span>
</div>
<div class="bd group">
<div class="sidebar">
<div class="searchlabel">
Search index:</div>
<div class="search" id="sidebarsearch">
<form id="qtdocsearch" action="" onsubmit="return false;">
<fieldset>
<input type="text" name="searchstring" id="pageType" value="" />
<div id="resultdialog">
<a href="#" id="resultclose">Close</a>
<p id="resultlinks" class="all"><a href="#" id="showallresults">All</a> | <a href="#" id="showapiresults">API</a> | <a href="#" id="showarticleresults">Articles</a> | <a href="#" id="showexampleresults">Examples</a></p>
<p id="searchcount" class="all"><span id="resultcount"></span><span id="apicount"></span><span id="articlecount"></span><span id="examplecount"></span> results:</p>
<ul id="resultlist" class="all">
</ul>
</div>
</fieldset>
</form>
</div>
<div class="box first bottombar" id="lookup">
<h2 title="API Lookup"><span></span>
API Lookup</h2>
<div id="list001" class="list">
<ul id="ul001" >
<li class="defaultLink"><a href="classes.html">Class index</a></li>
<li class="defaultLink"><a href="functions.html">Function index</a></li>
<li class="defaultLink"><a href="modules.html">Modules</a></li>
<li class="defaultLink"><a href="namespaces.html">Namespaces</a></li>
<li class="defaultLink"><a href="qtglobal.html">Global Declarations</a></li>
<li class="defaultLink"><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</div>
</div>
<div class="box bottombar" id="topics">
<h2 title="Qt Topics"><span></span>
Qt Topics</h2>
<div id="list002" class="list">
<ul id="ul002" >
<li class="defaultLink"><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li class="defaultLink"><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li class="defaultLink"><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li class="defaultLink"><a href="supported-platforms.html">Supported Platforms</a></li>
<li class="defaultLink"><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li class="defaultLink"><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</div>
</div>
<div class="box" id="examples">
<h2 title="Examples"><span></span>
Examples</h2>
<div id="list003" class="list">
<ul id="ul003">
<li class="defaultLink"><a href="all-examples.html">Examples</a></li>
<li class="defaultLink"><a href="tutorials.html">Tutorials</a></li>
<li class="defaultLink"><a href="demos.html">Demos</a></li>
<li class="defaultLink"><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</div>
</div>
</div>
<div class="wrap">
<div class="toolbar">
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li><a href="all-examples.html">Examples</a></li>
<li>Plug &amp; Paint Basic Tools Example</li>
</ul>
</div>
<div class="toolbuttons toolblock">
<ul>
<li id="smallA" class="t_button">A</li>
<li id="medA" class="t_button active">A</li>
<li id="bigA" class="t_button">A</li>
<li id="print" class="t_button"><a href="javascript:this.print();">
<span>Print</span></a></li>
</ul>
</div>
</div>
<div class="content mainContent">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#declaration-of-the-plugin-class">Declaration of the Plugin Class</a></li>
<li class="level1"><a href="#implementation-of-the-brush-interface">Implementation of the Brush Interface</a></li>
<li class="level1"><a href="#implementation-of-the-shape-interface">Implementation of the Shape Interface</a></li>
<li class="level1"><a href="#implementation-of-the-filter-interface">Implementation of the Filter Interface</a></li>
<li class="level1"><a href="#exporting-the-plugin">Exporting the Plugin</a></li>
<li class="level1"><a href="#the-pro-file">The .pro File</a></li>
</ul>
</div>
<h1 class="title">Plug & Paint Basic Tools Example</h1>
<span class="subtitle"></span>
<!-- $$$tools/plugandpaintplugins/basictools-description -->
<div class="descr"> <a name="details"></a>
<p>Files:</p>
<ul>
<li><a href="tools-plugandpaintplugins-basictools-basictoolsplugin-cpp.html">tools/plugandpaintplugins/basictools/basictoolsplugin.cpp</a></li>
<li><a href="tools-plugandpaintplugins-basictools-basictoolsplugin-h.html">tools/plugandpaintplugins/basictools/basictoolsplugin.h</a></li>
<li><a href="tools-plugandpaintplugins-basictools-basictools-pro.html">tools/plugandpaintplugins/basictools/basictools.pro</a></li>
</ul>
<p>The Basic Tools example is a static plugin for the <a href="tools-plugandpaint.html">Plug & Paint</a> example. It provides a set of basic brushes, shapes, and filters. Through the Basic Tools example, we will review the four steps involved in writing a Qt plugin:</p>
<ol class="1">
<li>Declare a plugin class.</li>
<li>Implement the interfaces provided by the plugin.</li>
<li>Export the plugin using the <a href="qtplugin.html#Q_EXPORT_PLUGIN2">Q_EXPORT_PLUGIN2</a>() macro.</li>
<li>Build the plugin using an adequate <tt>.pro</tt> file.</li>
</ol>
<a name="declaration-of-the-plugin-class"></a>
<h2>Declaration of the Plugin Class</h2>
<pre class="cpp"> <span class="preprocessor">#include <plugandpaint/interfaces.h></span>
<span class="keyword">class</span> BasicToolsPlugin : <span class="keyword">public</span> <span class="type"><a href="qobject.html">QObject</a></span><span class="operator">,</span>
<span class="keyword">public</span> BrushInterface<span class="operator">,</span>
<span class="keyword">public</span> ShapeInterface<span class="operator">,</span>
<span class="keyword">public</span> FilterInterface
{
Q_OBJECT
Q_INTERFACES(BrushInterface ShapeInterface FilterInterface)</pre>
<p>We start by including <tt>interfaces.h</tt>, which defines the plugin interfaces for the <a href="tools-plugandpaint.html">Plug & Paint</a> application. For the <tt>#include</tt> to work, we need to add an <tt>INCLUDEPATH</tt> entry to the <tt>.pro</tt> file with the path to Qt's <tt>examples/tools</tt> directory.</p>
<p>The <tt>BasicToolsPlugin</tt> class is a <a href="qobject.html">QObject</a> subclass that implements the <tt>BrushInterface</tt>, the <tt>ShapeInterface</tt>, and the <tt>FilterInterface</tt>. This is done through multiple inheritance. The <tt>Q_INTERFACES()</tt> macro is necessary to tell <a href="moc.html#moc">moc</a>, Qt's meta-object compiler, that the base classes are plugin interfaces. Without the <tt>Q_INTERFACES()</tt> macro, we couldn't use <a href="qobject.html#qobject_cast">qobject_cast</a>() in the <a href="tools-plugandpaint.html">Plug & Paint</a> application to detect interfaces.</p>
<pre class="cpp"> <span class="keyword">public</span>:
<span class="comment">// BrushInterface</span>
<span class="type"><a href="qstringlist.html">QStringList</a></span> brushes() <span class="keyword">const</span>;
<span class="type"><a href="qrect.html">QRect</a></span> mousePress(<span class="keyword">const</span> <span class="type"><a href="qstring.html">QString</a></span> <span class="operator">&</span>brush<span class="operator">,</span> <span class="type"><a href="qpainter.html">QPainter</a></span> <span class="operator">&</span>painter<span class="operator">,</span>
<span class="keyword">const</span> <span class="type"><a href="qpoint.html">QPoint</a></span> <span class="operator">&</span>pos);
<span class="type"><a href="qrect.html">QRect</a></span> mouseMove(<span class="keyword">const</span> <span class="type"><a href="qstring.html">QString</a></span> <span class="operator">&</span>brush<span class="operator">,</span> <span class="type"><a href="qpainter.html">QPainter</a></span> <span class="operator">&</span>painter<span class="operator">,</span>
<span class="keyword">const</span> <span class="type"><a href="qpoint.html">QPoint</a></span> <span class="operator">&</span>oldPos<span class="operator">,</span> <span class="keyword">const</span> <span class="type"><a href="qpoint.html">QPoint</a></span> <span class="operator">&</span>newPos);
<span class="type"><a href="qrect.html">QRect</a></span> mouseRelease(<span class="keyword">const</span> <span class="type"><a href="qstring.html">QString</a></span> <span class="operator">&</span>brush<span class="operator">,</span> <span class="type"><a href="qpainter.html">QPainter</a></span> <span class="operator">&</span>painter<span class="operator">,</span>
<span class="keyword">const</span> <span class="type"><a href="qpoint.html">QPoint</a></span> <span class="operator">&</span>pos);
<span class="comment">// ShapeInterface</span>
<span class="type"><a href="qstringlist.html">QStringList</a></span> shapes() <span class="keyword">const</span>;
<span class="type"><a href="qpainterpath.html">QPainterPath</a></span> generateShape(<span class="keyword">const</span> <span class="type"><a href="qstring.html">QString</a></span> <span class="operator">&</span>shape<span class="operator">,</span> <span class="type"><a href="qwidget.html">QWidget</a></span> <span class="operator">*</span>parent);
<span class="comment">// FilterInterface</span>
<span class="type"><a href="qstringlist.html">QStringList</a></span> filters() <span class="keyword">const</span>;
<span class="type"><a href="qimage.html">QImage</a></span> filterImage(<span class="keyword">const</span> <span class="type"><a href="qstring.html">QString</a></span> <span class="operator">&</span>filter<span class="operator">,</span> <span class="keyword">const</span> <span class="type"><a href="qimage.html">QImage</a></span> <span class="operator">&</span>image<span class="operator">,</span>
<span class="type"><a href="qwidget.html">QWidget</a></span> <span class="operator">*</span>parent);
};</pre>
<p>In the <tt>public</tt> section of the class, we declare all the functions from the three interfaces.</p>
<a name="implementation-of-the-brush-interface"></a>
<h2>Implementation of the Brush Interface</h2>
<p>Let's now review the implementation of the <tt>BasicToolsPlugin</tt> member functions inherited from <tt>BrushInterface</tt>.</p>
<pre class="cpp"> <span class="type"><a href="qstringlist.html">QStringList</a></span> BasicToolsPlugin<span class="operator">::</span>brushes() <span class="keyword">const</span>
{
<span class="keyword">return</span> <span class="type"><a href="qstringlist.html">QStringList</a></span>() <span class="operator"><</span><span class="operator"><</span> tr(<span class="string">"Pencil"</span>) <span class="operator"><</span><span class="operator"><</span> tr(<span class="string">"Air Brush"</span>)
<span class="operator"><</span><span class="operator"><</span> tr(<span class="string">"Random Letters"</span>);
}</pre>
<p>The <tt>brushes()</tt> function returns a list of brushes provided by this plugin. We provide three brushes: <b>Pencil</b>, <b>Air Brush</b>, and <b>Random Letters</b>.</p>
<pre class="cpp"> <span class="type"><a href="qrect.html">QRect</a></span> BasicToolsPlugin<span class="operator">::</span>mousePress(<span class="keyword">const</span> <span class="type"><a href="qstring.html">QString</a></span> <span class="operator">&</span>brush<span class="operator">,</span> <span class="type"><a href="qpainter.html">QPainter</a></span> <span class="operator">&</span>painter<span class="operator">,</span>
<span class="keyword">const</span> <span class="type"><a href="qpoint.html">QPoint</a></span> <span class="operator">&</span>pos)
{
<span class="keyword">return</span> mouseMove(brush<span class="operator">,</span> painter<span class="operator">,</span> pos<span class="operator">,</span> pos);
}</pre>
<p>On a mouse press event, we just call <tt>mouseMove()</tt> to draw the spot where the event occurred.</p>
<pre class="cpp"> <span class="type"><a href="qrect.html">QRect</a></span> BasicToolsPlugin<span class="operator">::</span>mouseMove(<span class="keyword">const</span> <span class="type"><a href="qstring.html">QString</a></span> <span class="operator">&</span>brush<span class="operator">,</span> <span class="type"><a href="qpainter.html">QPainter</a></span> <span class="operator">&</span>painter<span class="operator">,</span>
<span class="keyword">const</span> <span class="type"><a href="qpoint.html">QPoint</a></span> <span class="operator">&</span>oldPos<span class="operator">,</span> <span class="keyword">const</span> <span class="type"><a href="qpoint.html">QPoint</a></span> <span class="operator">&</span>newPos)
{
painter<span class="operator">.</span>save();
<span class="type">int</span> rad <span class="operator">=</span> painter<span class="operator">.</span>pen()<span class="operator">.</span>width() <span class="operator">/</span> <span class="number">2</span>;
<span class="type"><a href="qrect.html">QRect</a></span> boundingRect <span class="operator">=</span> <span class="type"><a href="qrect.html">QRect</a></span>(oldPos<span class="operator">,</span> newPos)<span class="operator">.</span>normalized()
<span class="operator">.</span>adjusted(<span class="operator">-</span>rad<span class="operator">,</span> <span class="operator">-</span>rad<span class="operator">,</span> <span class="operator">+</span>rad<span class="operator">,</span> <span class="operator">+</span>rad);
<span class="type"><a href="qcolor.html">QColor</a></span> color <span class="operator">=</span> painter<span class="operator">.</span>pen()<span class="operator">.</span>color();
<span class="type">int</span> thickness <span class="operator">=</span> painter<span class="operator">.</span>pen()<span class="operator">.</span>width();
<span class="type"><a href="qcolor.html">QColor</a></span> transparentColor(color<span class="operator">.</span>red()<span class="operator">,</span> color<span class="operator">.</span>green()<span class="operator">,</span> color<span class="operator">.</span>blue()<span class="operator">,</span> <span class="number">0</span>);</pre>
<p>In <tt>mouseMove()</tt>, we start by saving the state of the <a href="qpainter.html">QPainter</a> and we compute a few variables that we'll need later.</p>
<pre class="cpp"> <span class="keyword">if</span> (brush <span class="operator">=</span><span class="operator">=</span> tr(<span class="string">"Pencil"</span>)) {
painter<span class="operator">.</span>drawLine(oldPos<span class="operator">,</span> newPos);
} <span class="keyword">else</span> <span class="keyword">if</span> (brush <span class="operator">=</span><span class="operator">=</span> tr(<span class="string">"Air Brush"</span>)) {
<span class="type">int</span> numSteps <span class="operator">=</span> <span class="number">2</span> <span class="operator">+</span> (newPos <span class="operator">-</span> oldPos)<span class="operator">.</span>manhattanLength() <span class="operator">/</span> <span class="number">2</span>;
painter<span class="operator">.</span>setBrush(<span class="type"><a href="qbrush.html">QBrush</a></span>(color<span class="operator">,</span> <span class="type"><a href="qt.html">Qt</a></span><span class="operator">::</span>Dense6Pattern));
painter<span class="operator">.</span>setPen(<span class="type"><a href="qt.html">Qt</a></span><span class="operator">::</span>NoPen);
<span class="keyword">for</span> (<span class="type">int</span> i <span class="operator">=</span> <span class="number">0</span>; i <span class="operator"><</span> numSteps; <span class="operator">+</span><span class="operator">+</span>i) {
<span class="type">int</span> x <span class="operator">=</span> oldPos<span class="operator">.</span>x() <span class="operator">+</span> i <span class="operator">*</span> (newPos<span class="operator">.</span>x() <span class="operator">-</span> oldPos<span class="operator">.</span>x()) <span class="operator">/</span> (numSteps <span class="operator">-</span> <span class="number">1</span>);
<span class="type">int</span> y <span class="operator">=</span> oldPos<span class="operator">.</span>y() <span class="operator">+</span> i <span class="operator">*</span> (newPos<span class="operator">.</span>y() <span class="operator">-</span> oldPos<span class="operator">.</span>y()) <span class="operator">/</span> (numSteps <span class="operator">-</span> <span class="number">1</span>);
painter<span class="operator">.</span>drawEllipse(x <span class="operator">-</span> (thickness <span class="operator">/</span> <span class="number">2</span>)<span class="operator">,</span> y <span class="operator">-</span> (thickness <span class="operator">/</span> <span class="number">2</span>)<span class="operator">,</span>
thickness<span class="operator">,</span> thickness);
}
} <span class="keyword">else</span> <span class="keyword">if</span> (brush <span class="operator">=</span><span class="operator">=</span> tr(<span class="string">"Random Letters"</span>)) {
<span class="type"><a href="qchar.html">QChar</a></span> ch(<span class="char">'A'</span> <span class="operator">+</span> (qrand() <span class="operator">%</span> <span class="number">26</span>));
<span class="type"><a href="qfont.html">QFont</a></span> biggerFont <span class="operator">=</span> painter<span class="operator">.</span>font();
biggerFont<span class="operator">.</span>setBold(<span class="keyword">true</span>);
biggerFont<span class="operator">.</span>setPointSize(biggerFont<span class="operator">.</span>pointSize() <span class="operator">+</span> thickness);
painter<span class="operator">.</span>setFont(biggerFont);
painter<span class="operator">.</span>drawText(newPos<span class="operator">,</span> <span class="type"><a href="qstring.html">QString</a></span>(ch));
<span class="type"><a href="qfontmetrics.html">QFontMetrics</a></span> metrics(painter<span class="operator">.</span>font());
boundingRect <span class="operator">=</span> metrics<span class="operator">.</span>boundingRect(ch);
boundingRect<span class="operator">.</span>translate(newPos);
boundingRect<span class="operator">.</span>adjust(<span class="operator">-</span><span class="number">10</span><span class="operator">,</span> <span class="operator">-</span><span class="number">10</span><span class="operator">,</span> <span class="operator">+</span><span class="number">10</span><span class="operator">,</span> <span class="operator">+</span><span class="number">10</span>);
}
painter<span class="operator">.</span>restore();
<span class="keyword">return</span> boundingRect;
}</pre>
<p>Then comes the brush-dependent part of the code:</p>
<ul>
<li>If the brush is <b>Pencil</b>, we just call <a href="qpainter.html#drawLine">QPainter::drawLine</a>() with the current <a href="qpen.html">QPen</a>.</li>
<li>If the brush is <b>Air Brush</b>, we start by setting the painter's <a href="qbrush.html">QBrush</a> to <a href="qt.html#BrushStyle-enum">Qt::Dense6Pattern</a> to obtain a dotted pattern. Then we draw a circle filled with that <a href="qbrush.html">QBrush</a> several times, resulting in a thick line.</li>
<li>If the brush is <b>Random Letters</b>, we draw a random letter at the new cursor position. Most of the code is for setting the font to be bold and larger than the default font and for computing an appropriate bounding rect.</li>
</ul>
<p>At the end, we restore the painter state to what it was upon entering the function and we return the bounding rectangle.</p>
<pre class="cpp"> <span class="type"><a href="qrect.html">QRect</a></span> BasicToolsPlugin<span class="operator">::</span>mouseRelease(<span class="keyword">const</span> <span class="type"><a href="qstring.html">QString</a></span> <span class="operator">&</span> <span class="comment">/* brush */</span><span class="operator">,</span>
<span class="type"><a href="qpainter.html">QPainter</a></span> <span class="operator">&</span> <span class="comment">/* painter */</span><span class="operator">,</span>
<span class="keyword">const</span> <span class="type"><a href="qpoint.html">QPoint</a></span> <span class="operator">&</span> <span class="comment">/* pos */</span>)
{
<span class="keyword">return</span> <span class="type"><a href="qrect.html">QRect</a></span>(<span class="number">0</span><span class="operator">,</span> <span class="number">0</span><span class="operator">,</span> <span class="number">0</span><span class="operator">,</span> <span class="number">0</span>);
}</pre>
<p>When the user releases the mouse, we do nothing and return an empty <a href="qrect.html">QRect</a>.</p>
<a name="implementation-of-the-shape-interface"></a>
<h2>Implementation of the Shape Interface</h2>
<pre class="cpp"> <span class="type"><a href="qstringlist.html">QStringList</a></span> BasicToolsPlugin<span class="operator">::</span>shapes() <span class="keyword">const</span>
{
<span class="keyword">return</span> <span class="type"><a href="qstringlist.html">QStringList</a></span>() <span class="operator"><</span><span class="operator"><</span> tr(<span class="string">"Circle"</span>) <span class="operator"><</span><span class="operator"><</span> tr(<span class="string">"Star"</span>) <span class="operator"><</span><span class="operator"><</span> tr(<span class="string">"Text..."</span>);
}</pre>
<p>The plugin provides three shapes: <b>Circle</b>, <b>Star</b>, and <b>Text...</b>. The three dots after <b>Text</b> are there because the shape pops up a dialog asking for more information. We know that the shape names will end up in a menu, so we include the three dots in the shape name.</p>
<p>A cleaner but more complicated design would have been to distinguish between the internal shape name and the name used in the user interface.</p>
<pre class="cpp"> <span class="type"><a href="qpainterpath.html">QPainterPath</a></span> BasicToolsPlugin<span class="operator">::</span>generateShape(<span class="keyword">const</span> <span class="type"><a href="qstring.html">QString</a></span> <span class="operator">&</span>shape<span class="operator">,</span>
<span class="type"><a href="qwidget.html">QWidget</a></span> <span class="operator">*</span>parent)
{
<span class="type"><a href="qpainterpath.html">QPainterPath</a></span> path;
<span class="keyword">if</span> (shape <span class="operator">=</span><span class="operator">=</span> tr(<span class="string">"Circle"</span>)) {
path<span class="operator">.</span>addEllipse(<span class="number">0</span><span class="operator">,</span> <span class="number">0</span><span class="operator">,</span> <span class="number">50</span><span class="operator">,</span> <span class="number">50</span>);
} <span class="keyword">else</span> <span class="keyword">if</span> (shape <span class="operator">=</span><span class="operator">=</span> tr(<span class="string">"Star"</span>)) {
path<span class="operator">.</span>moveTo(<span class="number">90</span><span class="operator">,</span> <span class="number">50</span>);
<span class="keyword">for</span> (<span class="type">int</span> i <span class="operator">=</span> <span class="number">1</span>; i <span class="operator"><</span> <span class="number">5</span>; <span class="operator">+</span><span class="operator">+</span>i) {
path<span class="operator">.</span>lineTo(<span class="number">50</span> <span class="operator">+</span> <span class="number">40</span> <span class="operator">*</span> cos(<span class="number">0.8</span> <span class="operator">*</span> i <span class="operator">*</span> Pi)<span class="operator">,</span>
<span class="number">50</span> <span class="operator">+</span> <span class="number">40</span> <span class="operator">*</span> sin(<span class="number">0.8</span> <span class="operator">*</span> i <span class="operator">*</span> Pi));
}
path<span class="operator">.</span>closeSubpath();
} <span class="keyword">else</span> <span class="keyword">if</span> (shape <span class="operator">=</span><span class="operator">=</span> tr(<span class="string">"Text..."</span>)) {
<span class="type"><a href="qstring.html">QString</a></span> text <span class="operator">=</span> <span class="type"><a href="qinputdialog.html">QInputDialog</a></span><span class="operator">::</span>getText(parent<span class="operator">,</span> tr(<span class="string">"Text Shape"</span>)<span class="operator">,</span>
tr(<span class="string">"Enter text:"</span>)<span class="operator">,</span>
<span class="type"><a href="qlineedit.html">QLineEdit</a></span><span class="operator">::</span>Normal<span class="operator">,</span> tr(<span class="string">"Qt"</span>));
<span class="keyword">if</span> (<span class="operator">!</span>text<span class="operator">.</span>isEmpty()) {
<span class="type"><a href="qfont.html">QFont</a></span> timesFont(<span class="string">"Times"</span><span class="operator">,</span> <span class="number">50</span>);
timesFont<span class="operator">.</span>setStyleStrategy(<span class="type"><a href="qfont.html">QFont</a></span><span class="operator">::</span>ForceOutline);
path<span class="operator">.</span>addText(<span class="number">0</span><span class="operator">,</span> <span class="number">0</span><span class="operator">,</span> timesFont<span class="operator">,</span> text);
}
}
<span class="keyword">return</span> path;
}</pre>
<p>The <tt>generateShape()</tt> creates a <a href="qpainterpath.html">QPainterPath</a> for the specified shape. If the shape is <b>Text</b>, we pop up a <a href="qinputdialog.html">QInputDialog</a> to let the user enter some text.</p>
<a name="implementation-of-the-filter-interface"></a>
<h2>Implementation of the Filter Interface</h2>
<pre class="cpp"> <span class="type"><a href="qstringlist.html">QStringList</a></span> BasicToolsPlugin<span class="operator">::</span>filters() <span class="keyword">const</span>
{
<span class="keyword">return</span> <span class="type"><a href="qstringlist.html">QStringList</a></span>() <span class="operator"><</span><span class="operator"><</span> tr(<span class="string">"Invert Pixels"</span>) <span class="operator"><</span><span class="operator"><</span> tr(<span class="string">"Swap RGB"</span>)
<span class="operator"><</span><span class="operator"><</span> tr(<span class="string">"Grayscale"</span>);
}</pre>
<p>The plugin provides three filters: <b>Invert Pixels</b>, <b>Swap RGB</b>, and <b>Grayscale</b>.</p>
<pre class="cpp"> <span class="type"><a href="qimage.html">QImage</a></span> BasicToolsPlugin<span class="operator">::</span>filterImage(<span class="keyword">const</span> <span class="type"><a href="qstring.html">QString</a></span> <span class="operator">&</span>filter<span class="operator">,</span> <span class="keyword">const</span> <span class="type"><a href="qimage.html">QImage</a></span> <span class="operator">&</span>image<span class="operator">,</span>
<span class="type"><a href="qwidget.html">QWidget</a></span> <span class="operator">*</span> <span class="comment">/* parent */</span>)
{
<span class="type"><a href="qimage.html">QImage</a></span> result <span class="operator">=</span> image<span class="operator">.</span>convertToFormat(<span class="type"><a href="qimage.html">QImage</a></span><span class="operator">::</span>Format_RGB32);
<span class="keyword">if</span> (filter <span class="operator">=</span><span class="operator">=</span> tr(<span class="string">"Invert Pixels"</span>)) {
result<span class="operator">.</span>invertPixels();
} <span class="keyword">else</span> <span class="keyword">if</span> (filter <span class="operator">=</span><span class="operator">=</span> tr(<span class="string">"Swap RGB"</span>)) {
result <span class="operator">=</span> result<span class="operator">.</span>rgbSwapped();
} <span class="keyword">else</span> <span class="keyword">if</span> (filter <span class="operator">=</span><span class="operator">=</span> tr(<span class="string">"Grayscale"</span>)) {
<span class="keyword">for</span> (<span class="type">int</span> y <span class="operator">=</span> <span class="number">0</span>; y <span class="operator"><</span> result<span class="operator">.</span>height(); <span class="operator">+</span><span class="operator">+</span>y) {
<span class="keyword">for</span> (<span class="type">int</span> x <span class="operator">=</span> <span class="number">0</span>; x <span class="operator"><</span> result<span class="operator">.</span>width(); <span class="operator">+</span><span class="operator">+</span>x) {
<span class="type">int</span> pixel <span class="operator">=</span> result<span class="operator">.</span>pixel(x<span class="operator">,</span> y);
<span class="type">int</span> gray <span class="operator">=</span> <a href="qcolor.html#qGray">qGray</a>(pixel);
<span class="type">int</span> alpha <span class="operator">=</span> <a href="qcolor.html#qAlpha">qAlpha</a>(pixel);
result<span class="operator">.</span>setPixel(x<span class="operator">,</span> y<span class="operator">,</span> <a href="qcolor.html#qRgba">qRgba</a>(gray<span class="operator">,</span> gray<span class="operator">,</span> gray<span class="operator">,</span> alpha));
}
}
}
<span class="keyword">return</span> result;
}</pre>
<p>The <tt>filterImage()</tt> function takes a filter name and a <a href="qimage.html">QImage</a> as parameters and returns an altered <a href="qimage.html">QImage</a>. The first thing we do is to convert the image to a 32-bit RGB format, to ensure that the algorithms will work as expected. For example, <a href="qimage.html#invertPixels">QImage::invertPixels</a>(), which is used to implement the <b>Invert Pixels</b> filter, gives counterintuitive results for 8-bit images, because they invert the indices into the color table instead of inverting the color table's entries.</p>
<a name="exporting-the-plugin"></a>
<h2>Exporting the Plugin</h2>
<p>Whereas applications have a <tt>main()</tt> function as their entry point, plugins need to contain exactly one occurrence of the <a href="qtplugin.html#Q_EXPORT_PLUGIN2">Q_EXPORT_PLUGIN2</a>() macro to specify which class provides the plugin:</p>
<pre class="cpp"> <a href="qtplugin.html#Q_EXPORT_PLUGIN2">Q_EXPORT_PLUGIN2</a>(pnp_basictools<span class="operator">,</span> BasicToolsPlugin)</pre>
<p>This line may appear in any <tt>.cpp</tt> file that is part of the plugin's source code.</p>
<a name="the-pro-file"></a>
<h2>The .pro File</h2>
<p>Here's the project file for building the Basic Tools plugin:</p>
<pre class="cpp"> TEMPLATE = lib
CONFIG += plugin static
INCLUDEPATH += ../..
HEADERS = basictoolsplugin.h
SOURCES = basictoolsplugin.cpp
TARGET = $$qtLibraryTarget(pnp_basictools)
DESTDIR = ../../plugandpaint/plugins</pre>
<p>The <tt>.pro</tt> file differs from typical <tt>.pro</tt> files in many respects. First, it starts with a <tt>TEMPLATE</tt> entry specifying <tt>lib</tt>. (The default template is <tt>app</tt>.) It also adds <tt>plugin</tt> to the <tt>CONFIG</tt> variable. This is necessary on some platforms to avoid generating symbolic links with version numbers in the file name, which is appropriate for most dynamic libraries but not for plugins.</p>
<p>To make the plugin a static plugin, all that is required is to specify <tt>static</tt> in addition to <tt>plugin</tt>. The <a href="tools-plugandpaintplugins-extrafilters.html">Extra Filters</a> plugin, which is compiled as a dynamic plugin, doesn't specify <tt>static</tt> in its <tt>.pro</tt> file.</p>
<p>The <tt>INCLUDEPATH</tt> variable sets the search paths for global headers (i.e., header files included using <tt>#include <...></tt>). We add Qt's <tt>examples/tools</tt> directory (strictly speaking, <tt>examples/tools/plugandpaintplugins/basictools/../..</tt>) to the list, so that we can include <tt><plugandpaint/interfaces.h></tt>.</p>
<p>The <tt>TARGET</tt> variable specifies which name we want to give the target library. We use <tt>pnp_</tt> as the prefix to show that the plugin is designed to work with Plug & Paint. On Unix, <tt>lib</tt> is also prepended to that name. On all platforms, a platform-specific suffix is appended (e.g., <tt>.dll</tt> on Windows, <tt>.a</tt> on Linux).</p>
<p>The <tt>CONFIG()</tt> code at the end is necessary for this example because the example is part of the Qt distribution and Qt can be configured to be built simultaneously in debug and in release modes. You don't need to for your own plugins.</p>
</div>
<!-- @@@tools/plugandpaintplugins/basictools -->
</div>
</div>
</div>
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2015 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.</p>
<br />
<p>
The documentation provided herein is licensed under the terms of the
<a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation
License version 1.3</a> as published by the Free Software Foundation.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
Qt and respective logos are trademarks of The Qt Company Ltd
in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
<script src="scripts/functions.js" type="text/javascript"></script>
</body>
</html>
