KPluginFactory

#include <KPluginFactory>

Inheritance diagram for KPluginFactory:

[legend]

Classes
struct	InheritanceChecker

struct	InheritanceWithMetaDataChecker

class	Result

Public Types
enum	ResultErrorReason { NO_PLUGIN_ERROR = 0, INVALID_PLUGIN, INVALID_FACTORY, INVALID_KPLUGINFACTORY_INSTANTIATION }

Signals
void	objectCreated (QObject *object)

Public Member Functions
	KPluginFactory ()

	~KPluginFactory () override

template<typename T >
T *	create (const QString &keyword, QObject *parent=nullptr, const QVariantList &args=QVariantList())

template<typename T >
T *	create (QObject *parent, const QStringList &args)

QObject *	create (QObject parent=nullptr, const char classname="QObject", const QStringList &args=QStringList())

template<typename T >
T *	create (QObject *parent=nullptr, const QVariantList &args=QVariantList())

template<typename T >
T *	create (QWidget parentWidget, QObject parent, const QString &keyword, const QVariantList &args=QVariantList())

template<typename T >
T *	create (QWidget parentWidget, QObject parent, const QVariantList &args={})

KPluginMetaData	metaData () const

void	setMetaData (const KPluginMetaData &metaData)

Public Member Functions inherited from QObject
	QObject (QObject *parent)

bool	blockSignals (bool block)

const QObjectList &	children () const const

QMetaObject::Connection	connect (const QObject sender, const char signal, const char *method, Qt::ConnectionType type) const const

void	deleteLater ()

void	destroyed (QObject *obj)

bool	disconnect (const char signal, const QObject receiver, const char *method) const const

bool	disconnect (const QObject receiver, const char method) const const

void	dumpObjectInfo ()

void	dumpObjectInfo () const const

void	dumpObjectTree ()

void	dumpObjectTree () const const

QList< QByteArray >	dynamicPropertyNames () const const

virtual bool	event (QEvent *e)

virtual bool	eventFilter (QObject watched, QEvent event)

T	findChild (const QString &name, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QString &name, Qt::FindChildOptions options) const const

bool	inherits (const char *className) const const

void	installEventFilter (QObject *filterObj)

bool	isWidgetType () const const

bool	isWindowType () const const

void	killTimer (int id)

virtual const QMetaObject *	metaObject () const const

void	moveToThread (QThread *targetThread)

QString	objectName () const const

void	objectNameChanged (const QString &objectName)

QObject *	parent () const const

QVariant	property (const char *name) const const

	Q_CLASSINFO (Name, Value)

	Q_DISABLE_COPY (Class)

	Q_DISABLE_COPY_MOVE (Class)

	Q_DISABLE_MOVE (Class)

	Q_EMIT Q_EMIT

	Q_ENUM (...)

	Q_ENUM_NS (...)

	Q_ENUMS (...)

	Q_FLAG (...)

	Q_FLAG_NS (...)

	Q_FLAGS (...)

	Q_GADGET Q_GADGET

	Q_INTERFACES (...)

	Q_INVOKABLE Q_INVOKABLE

	Q_NAMESPACE Q_NAMESPACE

	Q_NAMESPACE_EXPORT (EXPORT_MACRO)

	Q_OBJECT Q_OBJECT

	Q_PROPERTY (...)

	Q_REVISION Q_REVISION

	Q_SET_OBJECT_NAME (Object)

	Q_SIGNAL Q_SIGNAL

	Q_SIGNALS Q_SIGNALS

	Q_SLOT Q_SLOT

	Q_SLOTS Q_SLOTS

T	qFindChild (const QObject *obj, const QString &name)

QList< T >	qFindChildren (const QObject *obj, const QRegExp &regExp)

QList< T >	qFindChildren (const QObject *obj, const QString &name)

T	qobject_cast (const QObject *object)

T	qobject_cast (QObject *object)

	QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT

void	removeEventFilter (QObject *obj)

void	setObjectName (const QString &name)

void	setParent (QObject *parent)

bool	setProperty (const char *name, const QVariant &value)

bool	signalsBlocked () const const

int	startTimer (int interval, Qt::TimerType timerType)

int	startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)

QThread *	thread () const const

Static Public Member Functions
template<typename T >
static Result< T >	instantiatePlugin (const KPluginMetaData &data, QObject *parent=nullptr, const QVariantList &args={})

static Result< KPluginFactory >	loadFactory (const KPluginMetaData &data)

static QVariantList	stringListToVariantList (const QStringList &list)

static QStringList	variantListToStringList (const QVariantList &list)

Static Public Member Functions inherited from QObject
QMetaObject::Connection	connect (const QObject sender, const char signal, const QObject receiver, const char method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject context, Functor functor, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)

bool	disconnect (const QMetaObject::Connection &connection)

bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char method)

bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method)

bool	disconnect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method)

QString	tr (const char sourceText, const char disambiguation, int n)

QString	trUtf8 (const char sourceText, const char disambiguation, int n)

Protected Types
typedef QObject (	CreateInstanceFunction) (QWidget , QObject , const QVariantList &)

using	CreateInstanceWithMetaDataFunction = QObject ()(QWidget , QObject , const KPluginMetaData &, const QVariantList &)

template<bool B, class T = void>
using	enable_if_t = typename std::enable_if< B, T >::type

Protected Member Functions
	KPluginFactory (KPluginFactoryPrivate &dd)

virtual QObject *	create (const char iface, QWidget parentWidget, QObject *parent, const QVariantList &args, const QString &keyword)

virtual QObject *	createObject (QObject parent, const char className, const QStringList &args)

virtual KParts::Part *	createPartObject (QWidget parentWidget, QObject parent, const char *classname, const QStringList &args)

template<class T , enable_if_t< InheritanceChecker< T >::enabled, int > = 0>
void	registerPlugin ()

template<class T , enable_if_t< InheritanceWithMetaDataChecker< T >::enabled, int > = 0>
void	registerPlugin ()

template<class T , enable_if_t< InheritanceChecker< T >::enabled, int > = 0>
void	registerPlugin (const QString &keyword)

template<class T , enable_if_t< InheritanceWithMetaDataChecker< T >::enabled, int > = 0>
void	registerPlugin (const QString &keyword)

template<class T >
void	registerPlugin (const QString &keyword, CreateInstanceFunction instanceFunction)

template<class T >
void	registerPlugin (const QString &keyword, CreateInstanceWithMetaDataFunction instanceFunction)

template<class T >
void	registerPlugin (CreateInstanceWithMetaDataFunction instanceFunction)

Protected Member Functions inherited from QObject
virtual void	childEvent (QChildEvent *event)

virtual void	connectNotify (const QMetaMethod &signal)

virtual void	customEvent (QEvent *event)

virtual void	disconnectNotify (const QMetaMethod &signal)

bool	isSignalConnected (const QMetaMethod &signal) const const

int	receivers (const char *signal) const const

QObject *	sender () const const

int	senderSignalIndex () const const

virtual void	timerEvent (QTimerEvent *event)

Static Protected Member Functions
template<class impl , class ParentType >
static QObject *	createInstance (QWidget parentWidget, QObject parent, const QVariantList &args)

template<class impl >
static QObject *	createPartInstance (QWidget parentWidget, QObject parent, const QVariantList &args)

template<class impl >
static QObject *	createPartWithMetaDataInstance (QWidget parentWidget, QObject parent, const KPluginMetaData &metaData, const QVariantList &args)

template<class impl , class ParentType >
static QObject *	createWithMetaDataInstance (QWidget parentWidget, QObject parent, const KPluginMetaData &metaData, const QVariantList &args)

Protected Attributes
const std::unique_ptr< KPluginFactoryPrivate >	d_ptr

Related Functions
(Note that these are not member functions.)
#define	K_PLUGIN_CLASS(classname) K_PLUGIN_FACTORY(classname##Factory, registerPlugin<classname>();)

#define	K_PLUGIN_CLASS_WITH_JSON(classname, jsonFile) K_PLUGIN_FACTORY_WITH_JSON(classname##Factory, jsonFile, registerPlugin<classname>();)

#define	K_PLUGIN_FACTORY(name, pluginRegistrations) K_PLUGIN_FACTORY_WITH_BASEFACTORY(name, KPluginFactory, pluginRegistrations)

#define	K_PLUGIN_FACTORY_DECLARATION(name) K_PLUGIN_FACTORY_DECLARATION_WITH_BASEFACTORY(name, KPluginFactory)

#define	K_PLUGIN_FACTORY_DECLARATION_WITH_BASEFACTORY_SKEL(name, baseFactory, ...)

#define	K_PLUGIN_FACTORY_DEFINITION(name, pluginRegistrations) K_PLUGIN_FACTORY_DEFINITION_WITH_BASEFACTORY(name, KPluginFactory, pluginRegistrations)

#define	K_PLUGIN_FACTORY_WITH_JSON(name, jsonFile, pluginRegistrations) K_PLUGIN_FACTORY_WITH_BASEFACTORY_JSON(name, KPluginFactory, jsonFile, pluginRegistrations)

Additional Inherited Members
Properties inherited from QObject
	objectName

Public Attributes inherited from QObject
typedef	QObjectList

Detailed Description

KPluginFactory provides a convenient way to provide factory-style plugins. Qt plugins provide a singleton object, but a common pattern is for plugins to generate as many objects of a particular type as the application requires. By using KPluginFactory, you can avoid implementing the factory pattern yourself.

KPluginFactory also allows plugins to provide multiple different object types, indexed by keywords.

The objects created by KPluginFactory must inherit QObject, and must have a standard constructor pattern:

if the object is a KPart::Part, it must be of the form
T(QWidget *parentWidget, QObject *parent, const QVariantList &args)

or, since KF 5.77,
T(QWidget *parentWidget, QObject *parent, const KPluginMetaData &metaData, const QVariantList &args)
if it is a QWidget, it must be of the form
T(QWidget *parent, const QVariantList &args)

or, since KF 5.77,
T(QWidget *parent, const KPluginMetaData &metaData, const QVariantList &args)
otherwise it must be of the form
T(QObject *parent, const QVariantList &args)

or, since KF 5.77,
T(QObject *parent, const KPluginMetaData &metaData, const QVariantList &args)

You should typically use either K_PLUGIN_FACTORY() or K_PLUGIN_FACTORY_WITH_JSON() in your plugin code to create the factory. The typical pattern is

#include <KPluginFactory>
#include <plugininterface.h>
 
class MyPlugin : public PluginInterface
{
public:
    MyPlugin(QObject *parent, const QVariantList &args)
        : PluginInterface(parent)
    {}
};
 
K_PLUGIN_FACTORY(MyPluginFactory,
                 registerPlugin<MyPlugin>();
                )
#include <myplugin.moc>

If you want to write a custom KPluginFactory not using the standard macro(s) you can reimplement the create(const char *iface, QWidget *parentWidget, QObject *parent, const QVariantList &args, const QString &keyword) method.

Example:

class SomeScriptLanguageFactory : public KPluginFactory
{
    Q_OBJECT
public:
    SomeScriptLanguageFactory()
    {}
 
protected:
    virtual QObject *create(const char *iface, QWidget *parentWidget, QObject *parent, const QVariantList &args, const QString &keyword)
    {
        const QString identifier = QLatin1String(iface) + QLatin1Char('_') + keyword;
        // load scripting language module from the information in identifier
        // and return it:
        return object;
    }
};

To use such a custom KPluginFactory, use the K_PLUGIN_FACTORY_DECLARATION_WITH_BASEFACTORY and K_PLUGIN_FACTORY_DEFINITION_WITH_BASEFACTORY macros, passing in the name of the custom subclass as baseFactory .

If you want to load a library use KPluginLoader. The application that wants to instantiate plugin classes can do the following:

KPluginFactory *factory = KPluginLoader("libraryname").factory();
if (factory) {
    PluginInterface *p1 = factory->create<PluginInterface>(parent);
    OtherInterface *p2  = factory->create<OtherInterface>(parent);
    NextInterface *p3   = factory->create<NextInterface>("keyword1", parent);
    NextInterface *p3   = factory->create<NextInterface>("keyword2", parent);
}

Author: Matthias Kretz kretz.nosp@m.@kde.nosp@m..org; Bernhard Loos nhuh..nosp@m.put@.nosp@m.web.d.nosp@m.e

Definition at line 427 of file kpluginfactory.h.

Member Typedef Documentation

◆ CreateInstanceFunction

typedef QObject*(* KPluginFactory::CreateInstanceFunction) (QWidget *, QObject *, const QVariantList &)

protected

Function pointer type to a function that instantiates a plugin.

Definition at line 635 of file kpluginfactory.h.

◆ CreateInstanceWithMetaDataFunction

using KPluginFactory::CreateInstanceWithMetaDataFunction = QObject *(*)(QWidget *, QObject *, const KPluginMetaData &, const QVariantList &)

protected

Function pointer type to a function that instantiates a plugin, also taking a plugin metadata argument.

Since: 5.77

Definition at line 665 of file kpluginfactory.h.

Member Enumeration Documentation

◆ ResultErrorReason

enum KPluginFactory::ResultErrorReason

Since: 5.86

Definition at line 443 of file kpluginfactory.h.

Constructor & Destructor Documentation

◆ KPluginFactory()

KPluginFactory::KPluginFactory ( )

explicit

This constructor creates a factory for a plugin.

Definition at line 19 of file kpluginfactory.cpp.

◆ ~KPluginFactory()

KPluginFactory::~KPluginFactory ( )

overridedefault

This destroys the PluginFactory.

Member Function Documentation

◆ create() [1/7]

QObject * KPluginFactory::create	(	const char *	iface,
		QWidget *	parentWidget,
		QObject *	parent,
		const QVariantList &	args,
		const QString &	keyword
	)

protectedvirtual

This function is called when the factory asked to create an Object.

You may reimplement it to provide a very flexible factory. This is especially useful to provide generic factories for plugins implemented using a scripting language.

Parameters

iface	the staticMetaObject::className() string identifying the plugin interface that was requested. E.g. for KCModule plugins this string will be "KCModule".
parentWidget	only used if the requested plugin is a KPart.
parent	the parent object for the plugin object.
args	a plugin specific list of arbitrary arguments.
keyword	a string that uniquely identifies the plugin. If a KService is used this keyword is read from the X-KDE-PluginKeyword entry in the .desktop file.

Definition at line 205 of file kpluginfactory.cpp.

◆ create() [2/7]

template<typename T >

T * KPluginFactory::create	(	const QString &	keyword,
		QObject *	parent = `nullptr`,
		const QVariantList &	args = `QVariantList()`
	)

inline

Use this method to create an object.

It will try to create an object which inherits T and was registered with keyword.

Template Parameters

T	the interface for which an object should be created. The object will inherit `T`.

Parameters

keyword	the keyword of the object.
parent	the parent of the object. If `parent` is a widget type, it will also passed to the parentWidget argument of the CreateInstanceFunction for the object.
args	additional arguments which will be passed to the object.

Returns: pointer to the created object is returned, or nullptr if an error occurred.

Deprecated:: Since 5.89, use overload without keyword instead

Definition at line 950 of file kpluginfactory.h.

◆ create() [3/7]

template<typename T >

T* KPluginFactory::create	(	QObject *	parent,
		const QStringList &	args
	)

inline

Deprecated:: since 4.0 use create<T>(QObject *parent, const QVariantList &args)

Definition at line 585 of file kpluginfactory.h.

◆ create() [4/7]

QObject* KPluginFactory::create	(	QObject *	parent = `nullptr`,
		const char *	classname = `"QObject"`,
		const QStringList &	args = `QStringList()`
	)

inline

Deprecated:: since 4.0 use create<T>(QObject *parent, const QVariantList &args)

Definition at line 594 of file kpluginfactory.h.

◆ create() [5/7]

template<typename T >

T * KPluginFactory::create	(	QObject *	parent = `nullptr`,
		const QVariantList &	args = `QVariantList()`
	)

inline

Use this method to create an object.

It will try to create an object which inherits T. If it has multiple choices it's not defined which object will be returned, so be careful to request a unique interface or use keywords.

Template Parameters

T	the interface for which an object should be created. The object will inherit `T`.

Parameters

parent	the parent of the object. If `parent` is a widget type, it will also passed to the parentWidget argument of the CreateInstanceFunction for the object.
args	additional arguments which will be passed to the object.

Returns: pointer to the created object is returned, or nullptr if an error occurred.

Definition at line 936 of file kpluginfactory.h.

◆ create() [6/7]

template<typename T >

T * KPluginFactory::create	(	QWidget *	parentWidget,
		QObject *	parent,
		const QString &	keyword,
		const QVariantList &	args = `QVariantList()`
	)

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

keyword the keyword of the object.

Deprecated:: Since 5.89, use overload without keyword instead

Definition at line 977 of file kpluginfactory.h.

◆ create() [7/7]

template<typename T >

T * KPluginFactory::create	(	QWidget *	parentWidget,
		QObject *	parent,
		const QVariantList &	args = `{}`
	)

inline

Use this method to create an object.

It will try to create an object which inherits T This overload has an additional parentWidget argument, which is used by some plugins (e.g. Parts).

Template Parameters

T	the interface for which an object should be created. The object will inherit `T`.

Parameters

parentWidget	an additional parent widget.
parent	the parent of the object. If `parent` is a widget type, it will also passed to the parentWidget argument of the CreateInstanceFunction for the object.
args	additional arguments which will be passed to the object. Since 5.93 this has a default arg.

Returns: pointer to the created object is returned, or nullptr if an error occurred.

Definition at line 964 of file kpluginfactory.h.

◆ createObject()

QObject * KPluginFactory::createObject	(	QObject *	parent,
		const char *	className,
		const QStringList &	args
	)

protectedvirtual

Deprecated:: since 4.0 use create<T>(QObject *parent, const QVariantList &args)

Reimplemented in KParts::Factory.

Definition at line 185 of file kpluginfactory.cpp.

◆ createPartObject()

KParts::Part * KPluginFactory::createPartObject	(	QWidget *	parentWidget,
		QObject *	parent,
		const char *	classname,
		const QStringList &	args
	)

protectedvirtual

Deprecated:: since 4.0 use create<T>(QWidget *parentWidget, QObject *parent, const QString &keyword, const QVariantList &args)

Reimplemented in KParts::Factory, and KParts::GenericFactory< class >.

Definition at line 195 of file kpluginfactory.cpp.

◆ instantiatePlugin()

template<typename T >

static Result<T> KPluginFactory::instantiatePlugin	(	const KPluginMetaData &	data,
		QObject *	parent = `nullptr`,
		const QVariantList &	args = `{}`
	)

inlinestatic

Attempts to load the KPluginFactory and create a T instance from the given metadata.

KPluginFactory::Result<MyClass> pluginResult = KPluginFactory::instantiatePlugin<MyClass>(metaData, parent, args);
if (pluginResult) {
    // The plugin is valid and can be accessed
} else {
    // The pluginResult object contains information about the error
}

If there is no extra error handling needed the plugin can be directly accessed and checked if it is a nullptr

if (auto plugin = KPluginFactory::instantiatePlugin<MyClass>(metaData, parent, args).plugin) {
    // The plugin is valid and can be accessed
}

Parameters

data	KPluginMetaData from which the plugin should be loaded

Returns: Result object which contains the plugin instance and potentially error information

Since: 5.86

Definition at line 499 of file kpluginfactory.h.

◆ loadFactory()

KPluginFactory::Result< KPluginFactory > KPluginFactory::loadFactory ( const KPluginMetaData & data )

static

Attempts to load the KPluginFactory from the given metadata.

The errors will be logged using the kf.coreaddons debug category.

Parameters

data	KPluginMetaData from which the plugin should be loaded

Returns: Result object which contains the plugin instance and potentially error information

Since: 5.86

Definition at line 33 of file kpluginfactory.cpp.

◆ metaData()

KPluginMetaData KPluginFactory::metaData ( ) const

Returns: the metadata of the plugin

Since: 5.77

Definition at line 73 of file kpluginfactory.cpp.

◆ registerPlugin() [1/7]

template<class T , enable_if_t< InheritanceChecker< T >::enabled, int > = 0>

void KPluginFactory::registerPlugin ( )

inlineprotected

Overload for registerPlugin<T>(const QString &keyword, CreateInstanceFunction instanceFunction)

Uses a default instance creation function depending on the type of interface. If the interface inherits from

KParts::Part the function will call
new T(QWidget *parentWidget, QObject *parent, const QVariantList &args)
QWidget the function will call
new T(QWidget *parent, const QVariantList &args)
else the function will call
new T(QObject *parent, const QVariantList &args)

If those constructor methods are not callable this overload is not available.

Definition at line 747 of file kpluginfactory.h.

◆ registerPlugin() [2/7]

template<class T , enable_if_t< InheritanceWithMetaDataChecker< T >::enabled, int > = 0>

void KPluginFactory::registerPlugin ( )

inlineprotected

Uses a default instance creation function depending on the type of interface.

If the interface inherits from

KParts::Part the function will call
new T(QWidget *parentWidget, QObject *parent, const KPluginMetaData &metaData, const QVariantList &args)
QWidget the function will call
new T(QWidget *parent, const KPluginMetaData &metaData, const QVariantList &args)
else the function will call
new T(QObject *parent, const KPluginMetaData &metaData, const QVariantList &args)

If those constructor methods are not callable this overload is not available.

Definition at line 814 of file kpluginfactory.h.

◆ registerPlugin() [3/7]

template<class T , enable_if_t< InheritanceChecker< T >::enabled, int > = 0>

void KPluginFactory::registerPlugin ( const QString & keyword )

inlineprotected

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Deprecated:: Since 5.89, use overload without keyword instead

Definition at line 760 of file kpluginfactory.h.

◆ registerPlugin() [4/7]

template<class T , enable_if_t< InheritanceWithMetaDataChecker< T >::enabled, int > = 0>

void KPluginFactory::registerPlugin ( const QString & keyword )

inlineprotected

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Deprecated:: Since 5.89, use overload without keyword instead

Definition at line 842 of file kpluginfactory.h.

◆ registerPlugin() [5/7]

template<class T >

void KPluginFactory::registerPlugin	(	const QString &	keyword,
		CreateInstanceFunction	instanceFunction
	)

inlineprotected

Registers a metadata-less plugin with the factory.

Call this function from the constructor of the KPluginFactory subclass to make the create function able to instantiate the plugin when asked for an interface the plugin implements.

You can register as many plugin classes as you want as long as either the plugin interface or the keyword makes it unique. E.g. it is possible to register a KCModule and a KParts::Part without having to specify keywords since their interfaces differ.

Template Parameters

T	the name of the plugin class

Parameters

keyword	an optional keyword as unique identifier for the plugin. This allows you to put more than one plugin with the same interface into the same library using the same factory. X-KDE-PluginKeyword is a convenient way to specify the keyword in a desktop file.
instanceFunction	A function pointer to a function that creates an instance of the plugin.

Deprecated:: Since 5.89, providing a custom CreateInstanceFunction is deprecated. Use registerPlugin<T>() instead

Definition at line 720 of file kpluginfactory.h.

◆ registerPlugin() [6/7]

template<class T >

void KPluginFactory::registerPlugin	(	const QString &	keyword,
		CreateInstanceWithMetaDataFunction	instanceFunction
	)

inlineprotected

Registers a metadata-taking plugin with the factory.

Call this function from the constructor of the KPluginFactory subclass to make the create function able to instantiate the plugin when asked for an interface the plugin implements.

Template Parameters

T	the name of the plugin class

Parameters

keyword	An optional keyword as unique identifier for the plugin. This allows you to put more than one plugin with the same interface into the same library using the same factory. X-KDE-PluginKeyword is a convenient way to specify the keyword in a desktop file.
instanceFunction	A function pointer to a function that creates an instance of the plugin.

Deprecated:: Since 5.89, providing a custom CreateInstanceWithMetaDataFunction is deprecated. Use registerPlugin<T>() instead

Definition at line 789 of file kpluginfactory.h.

◆ registerPlugin() [7/7]

template<class T >

void KPluginFactory::registerPlugin ( CreateInstanceWithMetaDataFunction instanceFunction )

inlineprotected

Registers a plugin with the factory.

Call this function from the constructor of the KPluginFactory subclass to make the create function able to instantiate the plugin when asked for an interface the plugin implements.

Parameters

T	the name of the plugin class
instanceFunction	A function pointer to a function that creates an instance of the plugin.

Since: 5.96

Definition at line 830 of file kpluginfactory.h.

◆ setMetaData()

void KPluginFactory::setMetaData ( const KPluginMetaData & metaData )

Set the metadata about the plugin this factory generates.

Parameters

metaData the metadata about the plugin

Since: 5.77

Definition at line 80 of file kpluginfactory.cpp.

◆ stringListToVariantList()

QVariantList KPluginFactory::stringListToVariantList ( const QStringList & list )

static

Converts a QStringList to a QVariantList

Definition at line 274 of file kpluginfactory.cpp.

◆ variantListToStringList()

QStringList KPluginFactory::variantListToStringList ( const QVariantList & list )

static

Converts a QVariantList of strings to a QStringList

Definition at line 265 of file kpluginfactory.cpp.

Friends And Related Function Documentation

◆ K_PLUGIN_CLASS

#define K_PLUGIN_CLASS ( classname ) K_PLUGIN_FACTORY(classname##Factory, registerPlugin<classname>();)

Creates a KPluginFactory subclass and exports it as the root plugin object. Unlike K_PLUGIN_CLASS_WITH_JSON, this macro does not require json meta data.

This macro does the same as K_PLUGIN_FACTORY, but you only have to pass the class name. The factory name and registerPlugin call are deduced from the class name. This is also useful if you want to use static plugins, see the kcoreaddons_add_plugin CMake method.

Since: 5.90

Definition at line 291 of file kpluginfactory.h.

◆ K_PLUGIN_CLASS_WITH_JSON

#define K_PLUGIN_CLASS_WITH_JSON	(	classname,
		jsonFile
	)	K_PLUGIN_FACTORY_WITH_JSON(classname##Factory, jsonFile, registerPlugin<classname>();)

Create a KPluginFactory subclass and export it as the root plugin object with JSON metadata.

This macro does the same as K_PLUGIN_FACTORY_WITH_JSON, but you only have to pass the class name and the json file. The factory name and registerPlugin call are deduced from the class name.

#include <myplugin.moc>

in the same source file when that one has the name "myplugin.cpp".

Example (KF >= 5.77):

#include <KPluginFactory>
#include <plugininterface.h>
 
class MyPlugin : public PluginInterface
{
public:
    MyPlugin(QObject *parent, const KPluginMetaData &metaData, const QVariantList &args)
        : PluginInterface(parent)
    {}
};
 
K_PLUGIN_CLASS_WITH_JSON(MyPlugin, "metadata.json")
 
#include <myplugin.moc>

Example (backward-compatible with KF < 5.77):

#include <KPluginFactory>
#include <plugininterface.h>
 
class MyPlugin : public PluginInterface
{
public:
    MyPlugin(QObject *parent, const QVariantList &args)
        : PluginInterface(parent)
    {}
};
 
K_PLUGIN_CLASS_WITH_JSON(MyPlugin, "metadata.json")
 
#include <myplugin.moc>

See also: K_PLUGIN_FACTORY_WITH_JSON

Since: 5.44

Definition at line 274 of file kpluginfactory.h.

◆ K_PLUGIN_FACTORY

#define K_PLUGIN_FACTORY	(	name,
		pluginRegistrations
	)	K_PLUGIN_FACTORY_WITH_BASEFACTORY(name, KPluginFactory, pluginRegistrations)

Create a KPluginFactory subclass and export it as the root plugin object.

Parameters

name	the name of the KPluginFactory derived class.
pluginRegistrations	code to be inserted into the constructor of the class. Usually a series of registerPlugin() calls.

Note: K_PLUGIN_FACTORY declares the subclass including a Q_OBJECT macro. So you need to make sure to have Qt's moc run also for the source file where you use the macro. E.g. in projects using CMake and it's automoc feature, as usual you need to have a line
#include <myplugin.moc>

in the same source file when that one has the name "myplugin.cpp".

Example:

#include <KPluginFactory>
#include <plugininterface.h>
 
class MyPlugin : public PluginInterface
{
public:
    MyPlugin(QObject *parent, const QVariantList &args)
        : PluginInterface(parent)
    {}
};
 
K_PLUGIN_FACTORY(MyPluginFactory,
                 registerPlugin<MyPlugin>();
                )
 
#include <myplugin.moc>

If you want to compile a .json file into the plugin, use K_PLUGIN_FACTORY_WITH_JSON.

See also: K_PLUGIN_FACTORY_WITH_JSON; K_PLUGIN_FACTORY_DECLARATION; K_PLUGIN_FACTORY_DEFINITION

Definition at line 138 of file kpluginfactory.h.

◆ K_PLUGIN_FACTORY_DECLARATION

#define K_PLUGIN_FACTORY_DECLARATION ( name ) K_PLUGIN_FACTORY_DECLARATION_WITH_BASEFACTORY(name, KPluginFactory)

K_PLUGIN_FACTORY_DECLARATION declares the KPluginFactory subclass. This macro can be used in a header file.

Parameters

name	the name of the KPluginFactory derived class.

See also: K_PLUGIN_FACTORY; K_PLUGIN_FACTORY_DEFINITION

Definition at line 305 of file kpluginfactory.h.

◆ K_PLUGIN_FACTORY_DECLARATION_WITH_BASEFACTORY_SKEL

#define K_PLUGIN_FACTORY_DECLARATION_WITH_BASEFACTORY_SKEL	(	name,
		baseFactory,
		...
	)

Value:

    class name : public baseFactory                                                                                                                            \
    {                                                                                                                                                          \
        Q_OBJECT                                                                                                                                               \
        Q_INTERFACES(KPluginFactory)                                                                                                                           \
        __VA_ARGS__                                                                                                                                            \
    public:                                                                                                                                                    \
        explicit name();                                                                                                                                       \
        ~name();                                                                                                                                               \
    };

Declare a KPluginFactory subclass of the given base factory.

Parameters

name	the name of the KPluginFactory derived class.
baseFactory	the name of the base class (base factory) to use. This must be a KPluginFactory subclass with a default constructor.

Additional parameters may be additional Qt properties, such as Q_PLUGIN_METADATA.

Note: The base factory must be a subclass of KPluginFactory. While this macro is largely an implementation detail, factories that have a different create() interface can be declared through this macro. Normal use through other K_PLUGIN_FACTORY macros uses KPluginFactory as a base.; This macro is usually only an implementation detail for K_PLUGIN_FACTORY_DECLARATION_WITH_BASEFACTORY or K_PLUGIN_FACTORY_DECLARATION_WITH_BASEFACTORY_JSON .

Since: 5.80

Definition at line 63 of file kpluginfactory.h.

◆ K_PLUGIN_FACTORY_DEFINITION

#define K_PLUGIN_FACTORY_DEFINITION	(	name,
		pluginRegistrations
	)	K_PLUGIN_FACTORY_DEFINITION_WITH_BASEFACTORY(name, KPluginFactory, pluginRegistrations)

K_PLUGIN_FACTORY_DEFINITION defines the KPluginFactory subclass. This macro can not be used in a header file.

Parameters

name	the name of the KPluginFactory derived class.
pluginRegistrations	code to be inserted into the constructor of the class. Usually a series of registerPlugin() calls.

See also: K_PLUGIN_FACTORY; K_PLUGIN_FACTORY_DECLARATION

Definition at line 320 of file kpluginfactory.h.

◆ K_PLUGIN_FACTORY_WITH_JSON

#define K_PLUGIN_FACTORY_WITH_JSON	(	name,
		jsonFile,
		pluginRegistrations
	)	K_PLUGIN_FACTORY_WITH_BASEFACTORY_JSON(name, KPluginFactory, jsonFile, pluginRegistrations)

Create a KPluginFactory subclass and export it as the root plugin object with JSON metadata.

This macro does the same as K_PLUGIN_FACTORY, but adds a JSON file as plugin metadata. See Q_PLUGIN_METADATA() for more information.

Parameters

name	the name of the KPluginFactory derived class.
pluginRegistrations	code to be inserted into the constructor of the class. Usually a series of registerPlugin() calls.
jsonFile	name of the JSON file to be compiled into the plugin as metadata

Note: K_PLUGIN_FACTORY_WITH_JSON declares the subclass including a Q_OBJECT macro. So you need to make sure to have Qt's moc run also for the source file where you use the macro. E.g. in projects using CMake and its automoc feature, as usual you need to have a line
#include <myplugin.moc>

in the same source file when that one has the name "myplugin.cpp".

Example (KF >= 5.77):

#include <KPluginFactory>
#include <plugininterface.h>
 
class MyPlugin : public PluginInterface
{
public:
    MyPlugin(QObject *parent, const KPluginMetaData &metaData, const QVariantList &args)
        : PluginInterface(parent)
    {}
};
 
K_PLUGIN_FACTORY_WITH_JSON(MyPluginFactory,
                 "metadata.json",
                 registerPlugin<MyPlugin>();
                )
 
#include <myplugin.moc>

Example (backward-compatible with KF < 5.77):

#include <KPluginFactory>
#include <plugininterface.h>
 
class MyPlugin : public PluginInterface
{
public:
    MyPlugin(QObject *parent, const QVariantList &args)
        : PluginInterface(parent)
    {}
};
 
K_PLUGIN_FACTORY_WITH_JSON(MyPluginFactory,
                 "metadata.json",
                 registerPlugin<MyPlugin>();
                )
 
#include <myplugin.moc>