Echo Plugin Example#
This example shows how to create a Qt plugin.
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 meta-object system . The plugin overview document gives a high-level introduction to plugins.
We have implemented a plugin, the
EchoPlugin, which implements the
EchoInterface. The interface consists of
echo(), which takes a
QString as argument. The
EchoPlugin returns the string unaltered (i.e., it works as the familiar echo command found in both Unix and Windows).
We test the plugin in
EchoWindow: when you push the
QPushButton (as seen in the image above), the application sends the text in the
QLineEdit to the plugin, which echoes it back to the application. The answer from the plugin is displayed in the
EchoWindow Class Definition#
EchoWindow class lets us test the
EchoPlugin through a GUI.
class EchoWindow(QWidget): Q_OBJECT # public EchoWindow() # private slots def sendEcho(): # private def createGUI(): loadPlugin = bool() echoInterface = EchoInterface() lineEdit = QLineEdit() label = QLabel() button = QPushButton() layout = QGridLayout()
We load the plugin in
loadPlugin() and cast it to
EchoInterface. When the user clicks the
button we take the text in
lineEdit and call the interface’s
echo() with it.
EchoWindow Class Implementation#
We start with a look at the constructor:
def __init__(self): createGUI() setLayout(layout) setWindowTitle("Echo Plugin Example") if not loadPlugin(): QMessageBox.information(self, "Error", "Could not load the plugin") lineEdit.setEnabled(False) button.setEnabled(False)
We create the widgets and set a title for the window. We then load the plugin.
loadPlugin() 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
errorString() ; we will look more closely at
Here is the implementation of
def sendEcho(self): text = echoInterface.echo(lineEdit.text()) label.setText(text)
This slot is called when the user pushes
button or presses enter in
lineEdit. We call
echo() of the echo interface. In our example this is the
EchoPlugin, but it could be any plugin that inherit the
EchoInterface. We take the
QString returned from
echo() and display it in the
Here is the implementation of
def createGUI(self): lineEdit = QLineEdit() label = QLabel() label.setFrameStyle(QFrame.Box | QFrame.Plain) button = QPushButton(tr("Send Message")) lineEdit.editingFinished.connect( self.sendEcho) button.clicked.connect( self.sendEcho) layout = QGridLayout() layout.addWidget(QLabel(tr("Message:")), 0, 0) layout.addWidget(lineEdit, 0, 1) layout.addWidget(QLabel(tr("Answer:")), 1, 0) layout.addWidget(label, 1, 1) layout.addWidget(button, 2, 1, Qt.AlignRight) layout.setSizeConstraint(QLayout.SetFixedSize)
We create the widgets and lay them out in a grid layout. We connect the label and line edit to our
Here is the
def loadPlugin(self): pluginsDir = QDir(QCoreApplication.applicationDirPath()) #if defined(Q_OS_WIN) if pluginsDir.dirName().toLower() == "debug" or pluginsDir.dirName().toLower() == "release": pluginsDir.cdUp() #elif defined(Q_OS_MAC) if pluginsDir.dirName() == "MacOS": pluginsDir.cdUp() pluginsDir.cdUp() pluginsDir.cdUp() #endif pluginsDir.cd("plugins") entries = pluginsDir.entryList(QDir.Files) for fileName in entries: pluginLoader = QPluginLoader(pluginsDir.absoluteFilePath(fileName)) plugin = pluginLoader.instance() if plugin: echoInterface = EchoInterface(plugin) if echoInterface: return True pluginLoader.unload() return False
Access to plugins at run-time is provided by
QPluginLoader . You supply it with the filename of the shared library the plugin is stored in and call
instance() , which loads and returns the root component of the plugin (i.e., it resolves the type of the plugin and creates a
QObject 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
EchoInterface and return true. In the case that the plugin loaded does not implement the
instance() will return null, but this cannot happen in our example. Notice that the location of the plugin is not the same for all platforms.
EchoInterface Class Definition#
EchoInterface 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.
class EchoInterface(): # public virtual ~EchoInterface() = default virtual QString echo(QString message) = 0 QT_BEGIN_NAMESPACE #define EchoInterface_iid "org.qt-project.Qt.Examples.EchoInterface" Q_DECLARE_INTERFACE(EchoInterface, EchoInterface_iid) QT_END_NAMESPACE
echo(). In our
EchoPlugin we use this method to return, or echo,
We use the
Q_DECLARE_INTERFACE macro to let Qt’s meta object system 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.
EchoPlugin Class Definition#
We inherit both
EchoInterface to make this class a plugin. The
Q_INTERFACES macro tells Qt which interfaces the class implements. In our case we only implement the
EchoInterface. If a class implements more than one interface, they are given as a space separated list. The
Q_PLUGIN_METADATA macro is included next to the
Q_OBJECT 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.
class EchoPlugin(QObject, EchoInterface): Q_OBJECT Q_PLUGIN_METADATA(IID "org.qt-project.Qt.Examples.EchoInterface" FILE "echoplugin.json") Q_INTERFACES(EchoInterface) # public echo = QString(QString message)
EchoPlugin Class Implementation#
Here is the implementation of
def echo(self, QString message): return message
We simply return the functions parameter.
The `` main()``
if __name__ == "__main__": app = QApplication(argv, args) window = EchoWindow() window.show() sys.exit(app.exec())
We create an
EchoWindow and display it as a top-level window.
When creating plugins the profiles need to be adjusted. We show here what changes need to be done.
The profile in the echoplugin directory uses the
subdirs template and simply includes includes to directories in which the echo window and echo plugin lives:
<Code snippet "tools/echoplugin/echoplugin.pro:0" not found>
The profile for the echo window does not need any plugin specific settings. We move on to the plugin profile:
<Code snippet "tools/echoplugin/plugin/plugin.pro:0" not found>
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
EchoInterface that the plugin implements lives in the
echowindow 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)
Further Reading and Examples#
The Defining Plugins page presents an overview of the macros needed to create plugins.
We give an example of a plugin that extends Qt in the style plugin example. The plug and paint example shows how to create static plugins.