Plugin System

Plugin system

Headunit Desktop comes with a plugin system that makes adding extensions to the system. Plugins need to be compiled into a library and placed in the sub-folder of the directory where HU is run from. If you'd like to add a plugin to the HU build then place your plugin in a folder that's named the same as the plugin the source directory's plugin directory ie: SOURCE_DIR/plugin/my-example-plugin. Then add the plugin to the headunit-desktop.pro file.

If you are writing a plugin then you need to extend the PluginInterface abstract class and implement the getContextProperty() function. PluginInterface can be found in the plugininterface.h file.

getContextProperty() has to return an object with QObject as base type. This will be loaded to the QML context as a property and will be referred to with the same name as the plugin.

Each plugin is configured using Q_PLUGIN_METADATA, set the id to something unique, HU built-in plugins use org.viktorgino.headunit.PLUGINNAME. Each plugin should have a plugin meta data definition ie: Q_PLUGIN_METADATA(IID "org.viktorgino.headunit.PLUGINNAME" FILE "config.json").

In your config.json you need to have a json object with each config having its own key. The name key is the absolute minimum that needs to be in there. The usage of the config file is as follows (you need to remove comments from the json file):

{
	"name":"PluginName",								//The name for the plugin, has to be an valid ES5 variable name
	"config":{											//Add plugin to the settings page
		"name":"plugin-name",							//Internal name for plugin
		"text":"Example Settings",						//Item name displayed on the settings page
		"source":"qrc:/ExampleSettings/settings.qml",	//The url to the QML file that contains your custom settings
		"iconImage": "qrc:/ExampleSettings/icon.png",	//The url for the icon that will be used on the settings page
		"section":"Examples"							//The section the settings item will be displayed at **currently not used**
	},
	"menu":{										//Add plugin to the side menu
		"text":"Example",							//Item name displayed in the menu
		"source":"qrc:/ExampleSettings/main.qml",	//The url to the QML file that contains your custom plugin
		"image": "qrc:/ExampleSettings/icon.png",	//The url for the icon that will be displayed in the menu
		"color":"#00BCD4"							//The colour for the menu item
	}	
}

It is recommended that you create your own plugin's prefix in any QML resource file to avoid mixing with other plugins etc.

Example plugin

Let's call our plugin example-plugin. You'll need 4 files for the skeleton of the plugin: main class and it header, config.json and a qt project file. In a real plugin you will also need a qrc file with the used qml files linked. You can have more classes which you can then load with the constructor of your implementation of PluginInterface.

example.pro

TEMPLATE = lib
CONFIG += c++11 plugin
QT += quick
TARGET = $$qtLibraryTarget(example-plugin)
DEFINES += QT_DEPRECATED_WARNINGS
INCLUDEPATH += ../../includes
DESTDIR = ../../plugins

SOURCES += \
	example.cpp

RESOURCES += qml.qrc

# Default rules for deployment.
qnx: target.path = /tmp/$${TARGET}/bin
else: unix:!android: target.path = /opt/$${TARGET}/bin
!isEmpty(target.path): INSTALLS += target

HEADERS += \
	example.h

example.h

#ifndef EXAMPLE_H
#define EXAMPLE_H

#include <QObject>
#include <plugininterface.h>

class Example : public QObject, PluginInterface
{
	Q_OBJECT
	Q_PLUGIN_METADATA(IID "org.viktorgino.headunit.example" FILE "config.json")
	Q_INTERFACES(PluginInterface)
public:
	explicit Example(QObject *parent = nullptr);
	QObject *getContextProperty() override;
private:
	ExampleClass *exampleContextProperty; //ExampleClass is fake class with QObject that extends QObject
signals:

public slots:
};

#endif // EXAMPLE_H

example.cpp

#include "example.h"

Example::Example(QObject *parent) : QObject(parent)
{
	exampleContextProperty = new ExampleClass();
}

QObject *Example::getContextProperty(){
	return qobject_cast<QObject *>(exampleContextProperty);
}

config.json

{
	"name":"ExamplePlugin",
	"config":{
		"name":"example-plugin",
		"text":"Example Settings",
		"source":"qrc:/ExampleSettings/settings.qml",
		"iconImage": "qrc:/ExampleSettings/icon.png",
		"section":"Examples"					
	},
	"menu":{
		"text":"Example",
		"source":"qrc:/ExampleSettings/main.qml",
		"image": "qrc:/ExampleSettings/icon.png",
		"color":"#00BCD4"
	}	
}