<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- echoplugin.qdoc -->
<title>Echo Plugin Example | Qt Widgets 5.9</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td >Qt 5.9</td><td ><a href="qtwidgets-index.html">Qt Widgets</a></td><td >Echo Plugin Example</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.9.4 Reference Documentation</td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#echowindow-class-definition">EchoWindow Class Definition</a></li>
<li class="level1"><a href="#echowindow-class-implementation">EchoWindow Class Implementation</a></li>
<li class="level1"><a href="#echointerface-class-definition">EchoInterface Class Definition</a></li>
<li class="level1"><a href="#echoplugin-class-definition">EchoPlugin Class Definition</a></li>
<li class="level1"><a href="#echoplugin-class-implementation">EchoPlugin Class Implementation</a></li>
<li class="level1"><a href="#the-main-function">The <code>main()</code> function</a></li>
<li class="level1"><a href="#the-profiles">The Profiles</a></li>
<li class="level1"><a href="#further-reading-and-examples">Further Reading and Examples</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Echo Plugin Example</h1>
<span class="subtitle"></span>
<!-- $$$tools/echoplugin-description -->
<div class="descr"> <a name="details"></a>
<p class="centerAlign"><img src="images/echopluginexample.png" alt="" /></p><p>There are two kinds of plugins in Qt: plugins that extend Qt itself and plugins that extend applications written in Qt. In this example, we show the procedure of implementing plugins that extend applications. When you create a plugin you declare an interface, which is a class with only pure virtual functions. This interface is inherited by the class that implements the plugin. The class is stored in a shared library and can therefore be loaded by applications at run-time. When loaded, the plugin is dynamically cast to the interface using Qt's <a href="../qtcore/metaobjects.html">meta-object system</a>. The plugin overview document gives a high-level introduction to plugins.</p>
<p>We have implemented a plugin, the <code>EchoPlugin</code>, which implements the <code>EchoInterface</code>. The interface consists of <code>echo()</code>, which takes a <a href="../qtcore/qstring.html">QString</a> as argument. The <code>EchoPlugin</code> returns the string unaltered (i.e., it works as the familiar echo command found in both Unix and Windows).</p>
<p>We test the plugin in <code>EchoWindow</code>: when you push the <a href="qpushbutton.html">QPushButton</a> (as seen in the image above), the application sends the text in the <a href="qlineedit.html">QLineEdit</a> to the plugin, which echoes it back to the application. The answer from the plugin is displayed in the <a href="qlabel.html">QLabel</a>.</p>
<a name="echowindow-class-definition"></a>
<h2 id="echowindow-class-definition">EchoWindow Class Definition</h2>
<p>The <code>EchoWindow</code> class lets us test the <code>EchoPlugin</code> through a GUI.</p>
<pre class="cpp">
<span class="keyword">class</span> EchoWindow : <span class="keyword">public</span> <span class="type"><a href="qwidget.html">QWidget</a></span>
{
Q_OBJECT
<span class="keyword">public</span>:
EchoWindow();
<span class="keyword">private</span> <span class="keyword">slots</span>:
<span class="type">void</span> sendEcho();
<span class="keyword">private</span>:
<span class="type">void</span> createGUI();
bool loadPlugin();
EchoInterface <span class="operator">*</span>echoInterface;
<span class="type"><a href="qlineedit.html">QLineEdit</a></span> <span class="operator">*</span>lineEdit;
<span class="type"><a href="qlabel.html">QLabel</a></span> <span class="operator">*</span>label;
<span class="type"><a href="qpushbutton.html">QPushButton</a></span> <span class="operator">*</span>button;
<span class="type"><a href="qgridlayout.html">QGridLayout</a></span> <span class="operator">*</span>layout;
};
</pre>
<p>We load the plugin in <code>loadPlugin()</code> and cast it to <code>EchoInterface</code>. When the user clicks the <code>button</code> we take the text in <code>lineEdit</code> and call the interface's <code>echo()</code> with it.</p>
<a name="echowindow-class-implementation"></a>
<h2 id="echowindow-class-implementation">EchoWindow Class Implementation</h2>
<p>We start with a look at the constructor:</p>
<pre class="cpp">
EchoWindow<span class="operator">::</span>EchoWindow()
{
createGUI();
setLayout(layout);
setWindowTitle(<span class="string">"Echo Plugin Example"</span>);
<span class="keyword">if</span> (<span class="operator">!</span>loadPlugin()) {
<span class="type"><a href="qmessagebox.html">QMessageBox</a></span><span class="operator">::</span>information(<span class="keyword">this</span><span class="operator">,</span> <span class="string">"Error"</span><span class="operator">,</span> <span class="string">"Could not load the plugin"</span>);
lineEdit<span class="operator">-</span><span class="operator">></span>setEnabled(<span class="keyword">false</span>);
button<span class="operator">-</span><span class="operator">></span>setEnabled(<span class="keyword">false</span>);
}
}
</pre>
<p>We create the widgets and set a title for the window. We then load the plugin. <code>loadPlugin()</code> returns false if the plugin could not be loaded, in which case we disable the widgets. If you wish a more detailed error message, you can use <a href="../qtcore/qpluginloader.html#errorString">errorString()</a>; we will look more closely at <a href="../qtcore/qpluginloader.html">QPluginLoader</a> later.</p>
<p>Here is the implementation of <code>sendEcho()</code>:</p>
<pre class="cpp">
<span class="type">void</span> EchoWindow<span class="operator">::</span>sendEcho()
{
<span class="type"><a href="../qtcore/qstring.html">QString</a></span> text <span class="operator">=</span> echoInterface<span class="operator">-</span><span class="operator">></span>echo(lineEdit<span class="operator">-</span><span class="operator">></span>text());
label<span class="operator">-</span><span class="operator">></span>setText(text);
}
</pre>
<p>This slot is called when the user pushes <code>button</code> or presses enter in <code>lineEdit</code>. We call <code>echo()</code> of the echo interface. In our example this is the <code>EchoPlugin</code>, but it could be any plugin that inherit the <code>EchoInterface</code>. We take the <a href="../qtcore/qstring.html">QString</a> returned from <code>echo()</code> and display it in the <code>label</code>.</p>
<p>Here is the implementation of <code>createGUI()</code>:</p>
<pre class="cpp">
<span class="type">void</span> EchoWindow<span class="operator">::</span>createGUI()
{
lineEdit <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qlineedit.html">QLineEdit</a></span>;
label <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qlabel.html">QLabel</a></span>;
label<span class="operator">-</span><span class="operator">></span>setFrameStyle(<span class="type"><a href="qframe.html">QFrame</a></span><span class="operator">::</span>Box <span class="operator">|</span> <span class="type"><a href="qframe.html">QFrame</a></span><span class="operator">::</span>Plain);
button <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qpushbutton.html">QPushButton</a></span>(tr(<span class="string">"Send Message"</span>));
connect(lineEdit<span class="operator">,</span> SIGNAL(editingFinished())<span class="operator">,</span>
<span class="keyword">this</span><span class="operator">,</span> SLOT(sendEcho()));
connect(button<span class="operator">,</span> SIGNAL(clicked())<span class="operator">,</span>
<span class="keyword">this</span><span class="operator">,</span> SLOT(sendEcho()));
layout <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qgridlayout.html">QGridLayout</a></span>;
layout<span class="operator">-</span><span class="operator">></span>addWidget(<span class="keyword">new</span> <span class="type"><a href="qlabel.html">QLabel</a></span>(tr(<span class="string">"Message:"</span>))<span class="operator">,</span> <span class="number">0</span><span class="operator">,</span> <span class="number">0</span>);
layout<span class="operator">-</span><span class="operator">></span>addWidget(lineEdit<span class="operator">,</span> <span class="number">0</span><span class="operator">,</span> <span class="number">1</span>);
layout<span class="operator">-</span><span class="operator">></span>addWidget(<span class="keyword">new</span> <span class="type"><a href="qlabel.html">QLabel</a></span>(tr(<span class="string">"Answer:"</span>))<span class="operator">,</span> <span class="number">1</span><span class="operator">,</span> <span class="number">0</span>);
layout<span class="operator">-</span><span class="operator">></span>addWidget(label<span class="operator">,</span> <span class="number">1</span><span class="operator">,</span> <span class="number">1</span>);
layout<span class="operator">-</span><span class="operator">></span>addWidget(button<span class="operator">,</span> <span class="number">2</span><span class="operator">,</span> <span class="number">1</span><span class="operator">,</span> <span class="type"><a href="../qtcore/qt.html">Qt</a></span><span class="operator">::</span>AlignRight);
layout<span class="operator">-</span><span class="operator">></span>setSizeConstraint(<span class="type"><a href="qlayout.html">QLayout</a></span><span class="operator">::</span>SetFixedSize);
}
</pre>
<p>We create the widgets and lay them out in a grid layout. We connect the label and line edit to our <code>sendEcho()</code> slot.</p>
<p>Here is the <code>loadPlugin()</code> function:</p>
<pre class="cpp">
bool EchoWindow<span class="operator">::</span>loadPlugin()
{
<span class="type"><a href="../qtcore/qdir.html">QDir</a></span> pluginsDir(qApp<span class="operator">-</span><span class="operator">></span>applicationDirPath());
<span class="preprocessor">#if defined(Q_OS_WIN)</span>
<span class="keyword">if</span> (pluginsDir<span class="operator">.</span>dirName()<span class="operator">.</span>toLower() <span class="operator">=</span><span class="operator">=</span> <span class="string">"debug"</span> <span class="operator">|</span><span class="operator">|</span> pluginsDir<span class="operator">.</span>dirName()<span class="operator">.</span>toLower() <span class="operator">=</span><span class="operator">=</span> <span class="string">"release"</span>)
pluginsDir<span class="operator">.</span>cdUp();
<span class="preprocessor">#elif defined(Q_OS_MAC)</span>
<span class="keyword">if</span> (pluginsDir<span class="operator">.</span>dirName() <span class="operator">=</span><span class="operator">=</span> <span class="string">"MacOS"</span>) {
pluginsDir<span class="operator">.</span>cdUp();
pluginsDir<span class="operator">.</span>cdUp();
pluginsDir<span class="operator">.</span>cdUp();
}
<span class="preprocessor">#endif</span>
pluginsDir<span class="operator">.</span>cd(<span class="string">"plugins"</span>);
foreach (<span class="type"><a href="../qtcore/qstring.html">QString</a></span> fileName<span class="operator">,</span> pluginsDir<span class="operator">.</span>entryList(<span class="type"><a href="../qtcore/qdir.html">QDir</a></span><span class="operator">::</span>Files)) {
<span class="type"><a href="../qtcore/qpluginloader.html">QPluginLoader</a></span> pluginLoader(pluginsDir<span class="operator">.</span>absoluteFilePath(fileName));
<span class="type"><a href="../qtcore/qobject.html">QObject</a></span> <span class="operator">*</span>plugin <span class="operator">=</span> pluginLoader<span class="operator">.</span>instance();
<span class="keyword">if</span> (plugin) {
echoInterface <span class="operator">=</span> qobject_cast<span class="operator"><</span>EchoInterface <span class="operator">*</span><span class="operator">></span>(plugin);
<span class="keyword">if</span> (echoInterface)
<span class="keyword">return</span> <span class="keyword">true</span>;
}
}
<span class="keyword">return</span> <span class="keyword">false</span>;
}
</pre>
<p>Access to plugins at run-time is provided by <a href="../qtcore/qpluginloader.html">QPluginLoader</a>. You supply it with the filename of the shared library the plugin is stored in and call <a href="../qtcore/qpluginloader.html#instance">instance()</a>, which loads and returns the root component of the plugin (i.e., it resolves the type of the plugin and creates a <a href="../qtcore/qobject.html">QObject</a> instance of it). If the plugin was not successfully loaded, it will be null, so we return false. If it was loaded correctly, we can cast the plugin to our <code>EchoInterface</code> and return true. In the case that the plugin loaded does not implement the <code>EchoInterface</code>, <code>instance()</code> will return null, but this cannot happen in our example. Notice that the location of the plugin is not the same for all platforms.</p>
<a name="echointerface-class-definition"></a>
<h2 id="echointerface-class-definition">EchoInterface Class Definition</h2>
<p>The <code>EchoInterface</code> defines the functions that the plugin will provide. An interface is a class that only consists of pure virtual functions. If non virtual functions were present in the class you would get misleading compile errors in the moc files.</p>
<pre class="cpp">
<span class="keyword">class</span> EchoInterface
{
<span class="keyword">public</span>:
<span class="keyword">virtual</span> <span class="operator">~</span>EchoInterface() {}
<span class="keyword">virtual</span> <span class="type"><a href="../qtcore/qstring.html">QString</a></span> echo(<span class="keyword">const</span> <span class="type"><a href="../qtcore/qstring.html">QString</a></span> <span class="operator">&</span>message) <span class="operator">=</span> <span class="number">0</span>;
};
<span class="preprocessor">#define EchoInterface_iid "org.qt-project.Qt.Examples.EchoInterface"</span>
Q_DECLARE_INTERFACE(EchoInterface<span class="operator">,</span> EchoInterface_iid)
</pre>
<p>We declare <code>echo()</code>. In our <code>EchoPlugin</code> we use this method to return, or echo, <i>message</i>.</p>
<p>We use the <a href="../qtcore/qtplugin.html#Q_DECLARE_INTERFACE">Q_DECLARE_INTERFACE</a> macro to let <a href="../qtcore/metaobjects.html">Qt's meta object system</a> aware of the interface. We do this so that it will be possible to identify plugins that implements the interface at run-time. The second argument is a string that must identify the interface in a unique way.</p>
<a name="echoplugin-class-definition"></a>
<h2 id="echoplugin-class-definition">EchoPlugin Class Definition</h2>
<p>We inherit both <a href="../qtcore/qobject.html">QObject</a> and <code>EchoInterface</code> to make this class a plugin. The <a href="../qtcore/qobject.html#Q_INTERFACES">Q_INTERFACES</a> macro tells Qt which interfaces the class implements. In our case we only implement the <code>EchoInterface</code>. If a class implements more than one interface, they are given as a space separated list. The <a href="../qtcore/qtplugin.html#Q_PLUGIN_METADATA">Q_PLUGIN_METADATA</a> macro is included next to the <a href="../qtcore/qobject.html#Q_OBJECT">Q_OBJECT</a> macro. It contains the plugins IID and a filename pointing to a json file containing the metadata for the plugin. The json file is compiled into the plugin and does not need to be installed.</p>
<pre class="cpp">
<span class="keyword">class</span> EchoPlugin : <span class="keyword">public</span> <span class="type"><a href="../qtcore/qobject.html">QObject</a></span><span class="operator">,</span> EchoInterface
{
Q_OBJECT
Q_PLUGIN_METADATA(IID <span class="string">"org.qt-project.Qt.Examples.EchoInterface"</span> FILE <span class="string">"echoplugin.json"</span>)
Q_INTERFACES(EchoInterface)
<span class="keyword">public</span>:
<span class="type"><a href="../qtcore/qstring.html">QString</a></span> echo(<span class="keyword">const</span> <span class="type"><a href="../qtcore/qstring.html">QString</a></span> <span class="operator">&</span>message) override;
};
</pre>
<a name="echoplugin-class-implementation"></a>
<h2 id="echoplugin-class-implementation">EchoPlugin Class Implementation</h2>
<p>Here is the implementation of <code>echo()</code>:</p>
<pre class="cpp">
<span class="type"><a href="../qtcore/qstring.html">QString</a></span> EchoPlugin<span class="operator">::</span>echo(<span class="keyword">const</span> <span class="type"><a href="../qtcore/qstring.html">QString</a></span> <span class="operator">&</span>message)
{
<span class="keyword">return</span> message;
}
</pre>
<p>We simply return the functions parameter.</p>
<a name="the-main-function"></a>
<h2 id="the-main-function">The <code>main()</code> function</h2>
<pre class="cpp">
<span class="type">int</span> main(<span class="type">int</span> argv<span class="operator">,</span> <span class="type">char</span> <span class="operator">*</span>args<span class="operator">[</span><span class="operator">]</span>)
{
<span class="type"><a href="qapplication.html">QApplication</a></span> app(argv<span class="operator">,</span> args);
EchoWindow window;
window<span class="operator">.</span>show();
<span class="keyword">return</span> app<span class="operator">.</span>exec();
}
</pre>
<p>We create an <code>EchoWindow</code> and display it as a top-level window.</p>
<a name="the-profiles"></a>
<h2 id="the-profiles">The Profiles</h2>
<p>When creating plugins the profiles need to be adjusted. We show here what changes need to be done.</p>
<p>The profile in the echoplugin directory uses the <code>subdirs</code> template and simply includes includes to directories in which the echo window and echo plugin lives:</p>
<pre class="cpp">
TEMPLATE = subdirs
SUBDIRS = echowindow \
plugin
</pre>
<p>The profile for the echo window does not need any plugin specific settings. We move on to the plugin profile:</p>
<pre class="cpp">
TEMPLATE = lib
CONFIG += plugin
QT += widgets
INCLUDEPATH += ../echowindow
HEADERS = echoplugin.h
SOURCES = echoplugin.cpp
TARGET = $$qtLibraryTarget(echoplugin)
DESTDIR = ../plugins
</pre>
<p>We need to set the TEMPLATE as we now want to make a library instead of an executable. We also need to tell qmake that we are creating a plugin. The <code>EchoInterface</code> that the plugin implements lives in the <code>echowindow</code> directory, so we need to add that directory to the include path. We set the TARGET of the project, which is the name of the library file in which the plugin will be stored; qmake appends the appropriate file extension depending on the platform. By convention the target should have the same name as the plugin (set with Q_EXPORT_PLUGIN2)</p>
<a name="further-reading-and-examples"></a>
<h2 id="further-reading-and-examples">Further Reading and Examples</h2>
<p>The <a href="../qtcore/qtplugin.html">Defining Plugins</a> page presents an overview of the macros needed to create plugins.</p>
<p>We give an example of a plugin that extends Qt in the <a href="qtwidgets-tools-styleplugin-example.html">style plugin</a> example. The <a href="qtwidgets-tools-plugandpaint-app-example.html">plug and paint</a> example shows how to create static plugins.</p>
<p>Files:</p>
<ul>
<li><a href="qtwidgets-tools-echoplugin-echowindow-echointerface-h.html">tools/echoplugin/echowindow/echointerface.h</a></li>
<li><a href="qtwidgets-tools-echoplugin-echowindow-echowindow-cpp.html">tools/echoplugin/echowindow/echowindow.cpp</a></li>
<li><a href="qtwidgets-tools-echoplugin-echowindow-echowindow-h.html">tools/echoplugin/echowindow/echowindow.h</a></li>
<li><a href="qtwidgets-tools-echoplugin-plugin-echoplugin-cpp.html">tools/echoplugin/plugin/echoplugin.cpp</a></li>
<li><a href="qtwidgets-tools-echoplugin-plugin-echoplugin-h.html">tools/echoplugin/plugin/echoplugin.h</a></li>
<li><a href="qtwidgets-tools-echoplugin-echowindow-main-cpp.html">tools/echoplugin/echowindow/main.cpp</a></li>
<li><a href="qtwidgets-tools-echoplugin-echoplugin-pro.html">tools/echoplugin/echoplugin.pro</a></li>
<li><a href="qtwidgets-tools-echoplugin-echowindow-echowindow-pro.html">tools/echoplugin/echowindow/echowindow.pro</a></li>
<li><a href="qtwidgets-tools-echoplugin-plugin-plugin-pro.html">tools/echoplugin/plugin/plugin.pro</a></li>
</ul>
</div>
<!-- @@@tools/echoplugin -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2017 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br> 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.<br> 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. </p>
</div>
</body>
</html>
distrib
>
Mageia
>
6
>
armv5tl
>
media
>
core-updates
>
by-pkgid
>
768f7d9f703884aa2562bf0a651086df
>
files
>
4304
