KDECore
KPluginFactory Class Reference
If you develop a library that is to be loaded dynamically at runtime, then you should return a pointer to a KPluginFactory. More...
#include <KPluginFactory>

Classes | |
struct | InheritanceChecker |
This is used to detect the arguments need for the constructor of plugin classes. More... | |
Signals | |
void | objectCreated (QObject *object) |
Public Member Functions | |
KComponentData | componentData () const |
KDE_DEPRECATED QObject * | create (QObject *parent=0, const char *classname="QObject", const QStringList &args=QStringList()) |
template<typename T > | |
KDE_DEPRECATED T * | create (QObject *parent, const QStringList &args) |
template<typename T > | |
T * | create (QWidget *parentWidget, QObject *parent, const QString &keyword=QString(), const QVariantList &args=QVariantList()) |
template<typename T > | |
T * | create (const QString &keyword, QObject *parent=0, const QVariantList &args=QVariantList()) |
template<typename T > | |
T * | create (QObject *parent=0, const QVariantList &args=QVariantList()) |
KDE_CONSTRUCTOR_DEPRECATED | KPluginFactory (QObject *parent) |
KDE_CONSTRUCTOR_DEPRECATED | KPluginFactory (const KAboutData *aboutData, QObject *parent=0) |
KPluginFactory (const KAboutData &aboutData, QObject *parent=0) | |
KPluginFactory (const char *componentName=0, const char *catalogName=0, QObject *parent=0) | |
virtual | ~KPluginFactory () |
Protected Types | |
typedef QObject *(* | CreateInstanceFunction )(QWidget *, QObject *, const QVariantList &) |
Protected Member Functions | |
virtual QObject * | create (const char *iface, QWidget *parentWidget, QObject *parent, const QVariantList &args, const QString &keyword) |
virtual KDE_DEPRECATED QObject * | createObject (QObject *parent, const char *className, const QStringList &args) |
virtual KDE_DEPRECATED KParts::Part * | createPartObject (QWidget *parentWidget, QObject *parent, const char *classname, const QStringList &args) |
KPluginFactory (KPluginFactoryPrivate &dd, QObject *parent=0) | |
template<class T > | |
void | registerPlugin (const QString &keyword=QString(), CreateInstanceFunction instanceFunction=InheritanceChecker< T >().createInstanceFunction(reinterpret_cast< T * >(0))) |
void | setComponentData (const KComponentData &componentData) |
virtual void | setupTranslations () |
QVariantList | stringListToVariantList (const QStringList &list) |
QStringList | variantListToStringList (const QVariantList &list) |
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) |
Protected Attributes | |
KPluginFactoryPrivate *const | d_ptr |
Related Functions | |
(Note that these are not member functions.) | |
K_PLUGIN_FACTORY(name, pluginRegistrations) | |
K_PLUGIN_FACTORY_DECLARATION(name) | |
K_PLUGIN_FACTORY_DEFINITION(name, pluginRegistrations) |
Detailed Description
If you develop a library that is to be loaded dynamically at runtime, then you should return a pointer to a KPluginFactory.
For most cases it is enough to use the K_PLUGIN_FACTORY macro to create the factory.
Example:
#include <KPluginFactory> #include <KPluginLoader> #include <plugininterface.h> class MyPlugin; K_PLUGIN_FACTORY(MyPluginFactory, registerPlugin<MyPlugin>(); ) K_EXPORT_PLUGIN(MyPluginFactory("componentName")) class MyPlugin : public PluginInterface { ... KComponentData kcd = MyPluginFactory::componentData(); ... };
K_PLUGIN_FACTORY is a convenient macro that expands to a class derived from KPluginFactory providing two constructors and a static componentData() function. The second argument to K_PLUGIN_FACTORY is code that is called from the constructors. There you can use registerPlugin to register as many plugins for the factory as you want to.
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) function.
Example:
class SomeScriptLanguageFactory : public KPluginFactory { Q_OBJECT public: SomeScriptLanguageFactory() : KPluginFactory("SomeScriptLanguageComponent") {} 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; } };
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); }
Definition at line 232 of file kpluginfactory.h.
Member Typedef Documentation
typedef QObject*(* KPluginFactory::CreateInstanceFunction)(QWidget *, QObject *, const QVariantList &) [protected] |
Function pointer type to a function that instantiates a plugin.
Definition at line 354 of file kpluginfactory.h.
Constructor & Destructor Documentation
KPluginFactory::KPluginFactory | ( | const char * | componentName = 0 , |
|
const char * | catalogName = 0 , |
|||
QObject * | parent = 0 | |||
) | [explicit] |
This constructor creates a factory for a plugin with the given componentName
and catalogName
.
Those values are used to initialize a KComponentData object for the plugin. You can later access it with componentData(). If componentName
is 0, an invalid KComponentData object will be created.
- Parameters:
-
componentName the component name of the plugin catalogName the translation catalog to use parent a parent object
Definition at line 31 of file kpluginfactory.cpp.
KPluginFactory::KPluginFactory | ( | const KAboutData & | aboutData, | |
QObject * | parent = 0 | |||
) | [explicit] |
This constructor creates a factory for a plugin with the given KAboutData object.
This object is used to initialize a KComponentData object for the plugin. You can later access it with componentData(). KPluginFactory takes ownership of the aboutData
object, so don't delete it yourself!
- Parameters:
-
aboutData the KAboutData for the plugin parent a parent object
Definition at line 53 of file kpluginfactory.cpp.
KPluginFactory::KPluginFactory | ( | const KAboutData * | aboutData, | |
QObject * | parent = 0 | |||
) | [explicit] |
Definition at line 43 of file kpluginfactory.cpp.
KPluginFactory::KPluginFactory | ( | QObject * | parent | ) | [explicit] |
Definition at line 63 of file kpluginfactory.cpp.
KPluginFactory::~KPluginFactory | ( | ) | [virtual] |
This destroys the PluginFactory.
It will remove the translation catalog for the plugin, if it was initialized.
Definition at line 77 of file kpluginfactory.cpp.
KPluginFactory::KPluginFactory | ( | KPluginFactoryPrivate & | dd, | |
QObject * | parent = 0 | |||
) | [explicit, protected] |
Definition at line 71 of file kpluginfactory.cpp.
Member Function Documentation
KComponentData KPluginFactory::componentData | ( | ) | const |
You can use this method to get the component data of the plugin.
It is filled with the information given to the constructor of KPluginFactory. The K_PLUGIN_FACTORY macros provide a static version of this method, this can be used from any place within the plugin.
- Returns:
- The KComponentData for the plugin
Definition at line 88 of file kpluginfactory.cpp.
QObject * KPluginFactory::create | ( | const char * | iface, | |
QWidget * | parentWidget, | |||
QObject * | parent, | |||
const QVariantList & | args, | |||
const QString & | keyword | |||
) | [protected, virtual] |
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 implemeted 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 151 of file kpluginfactory.cpp.
KDE_DEPRECATED QObject* KPluginFactory::create | ( | QObject * | parent = 0 , |
|
const char * | classname = "QObject" , |
|||
const QStringList & | args = QStringList() | |||
) | [inline] |
Definition at line 342 of file kpluginfactory.h.
KDE_DEPRECATED T* KPluginFactory::create | ( | QObject * | parent, | |
const QStringList & | args | |||
) | [inline] |
Definition at line 334 of file kpluginfactory.h.
T * KPluginFactory::create | ( | QWidget * | parentWidget, | |
QObject * | parent, | |||
const QString & | keyword = QString() , |
|||
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
. 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.keyword The keyword of the object. args Additional arguments which will be passed to the object.
- Returns:
- A pointer to the created object is returned, or 0 if an error occurred.
Definition at line 513 of file kpluginfactory.h.
T * KPluginFactory::create | ( | const QString & | keyword, | |
QObject * | parent = 0 , |
|||
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:
- A pointer to the created object is returned, or 0 if an error occurred.
Definition at line 501 of file kpluginfactory.h.
T * KPluginFactory::create | ( | QObject * | parent = 0 , |
|
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, you will get a fatal error (kFatal()), so be creaful 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:
- A pointer to the created object is returned, or 0 if an error occurred.
Definition at line 489 of file kpluginfactory.h.
static QObject* KPluginFactory::createInstance | ( | QWidget * | parentWidget, | |
QObject * | parent, | |||
const QVariantList & | args | |||
) | [inline, static, protected] |
Definition at line 453 of file kpluginfactory.h.
QObject * KPluginFactory::createObject | ( | QObject * | parent, | |
const char * | className, | |||
const QStringList & | args | |||
) | [protected, virtual] |
static QObject* KPluginFactory::createPartInstance | ( | QWidget * | parentWidget, | |
QObject * | parent, | |||
const QVariantList & | args | |||
) | [inline, static, protected] |
Definition at line 465 of file kpluginfactory.h.
KParts::Part * KPluginFactory::createPartObject | ( | QWidget * | parentWidget, | |
QObject * | parent, | |||
const char * | classname, | |||
const QStringList & | args | |||
) | [protected, virtual] |
Definition at line 142 of file kpluginfactory.cpp.
void KPluginFactory::objectCreated | ( | QObject * | object | ) | [signal] |
void KPluginFactory::registerPlugin | ( | const QString & | keyword = QString() , |
|
CreateInstanceFunction | instanceFunction = InheritanceChecker<T>().createInstanceFunction(reinterpret_cast<T *>(0)) | |||
) | [inline, protected] |
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.
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. The default function that will be used depends on the type of interface. If the interface inherits from KParts::Part
the function will callQWidget
the function will callnew T(QWidget *parent, const QVariantList &args)
- else the function will call
Definition at line 390 of file kpluginfactory.h.
void KPluginFactory::setComponentData | ( | const KComponentData & | componentData | ) | [protected] |
This method sets the component data of the plugin.
You can access the component data object later with componentData(). Normally you don't have to call this, because the factory constructs a component data object from the information given to the constructor. The object is destroyed, when the module containing the plugin is unloaded. Normally this happens only on application shutdown.
- Parameters:
-
componentData the new KComponentData object
Definition at line 213 of file kpluginfactory.cpp.
void KPluginFactory::setupTranslations | ( | ) | [protected, virtual] |
Definition at line 203 of file kpluginfactory.cpp.
QVariantList KPluginFactory::stringListToVariantList | ( | const QStringList & | list | ) | [protected] |
For internal use only.
Converts a QStringList to a QVariantList
Definition at line 229 of file kpluginfactory.cpp.
QStringList KPluginFactory::variantListToStringList | ( | const QVariantList & | list | ) | [protected] |
For internal use only.
Converts a QVariantList of strings to a QStringList
Definition at line 220 of file kpluginfactory.cpp.
Friends And Related Function Documentation
K_PLUGIN_FACTORY | ( | name, | |||
pluginRegistrations | ) | [related] |
Defines a KPluginFactory subclass with two constructors and a static componentData function.
The first constructor takes the arguments (const char *componentName, const char *catalogName, QObject *parent). The second constructor takes (const KAboutData *aboutData, QObject *parent).
The static componentData method returns the same KComponentData object as the KPluginFactory::componentData function returns. As you normally don't have a pointer to the factory object in the plugin code the static componentData function is a convenient way to access the KComponentData.
- Parameters:
-
name The name of the KPluginFactory derived class. This is the name you'll need for K_EXPORT_PLUGIN pluginRegistrations This is code inserted into the constructors the class. You'll want to call registerPlugin from there.
Example:
#include <KPluginFactory> #include <KPluginLoader> #include <plugininterface.h> class MyPlugin; K_PLUGIN_FACTORY(MyPluginFactory, registerPlugin<MyPlugin>(); ) K_EXPORT_PLUGIN(MyPluginFactory("componentName", "catalogName")) // or: static KAboutData createAboutData() { KAboutData aboutData("myplugin", "myplugin", ki18n("MyPlugin"), "0.1", ki18n("a description of the plugin"), KAboutData::License_LGPL, ki18n("Copyright (C) 2007 Your Name")); aboutData.addAuthor(ki18n("Your Name"), ...); return aboutData; } K_EXPORT_PLUGIN(MyPluginFactory(createAboutData())) class MyPlugin : public PluginInterface { ... KComponentData kcd = MyPluginFactory::componentData(); ... };
Definition at line 127 of file kpluginfactory.h.
K_PLUGIN_FACTORY_DECLARATION | ( | name | ) | [related] |
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. This is the name you'll need for K_EXPORT_PLUGIN
Definition at line 140 of file kpluginfactory.h.
K_PLUGIN_FACTORY_DEFINITION | ( | name, | |||
pluginRegistrations | ) | [related] |
K_PLUGIN_FACTORY_DECLARATION defines the KPluginFactory subclass. This macro can not be used in a header file.
- Parameters:
-
name The name of the KPluginFactory derived class. This is the name you'll need for K_EXPORT_PLUGIN pluginRegistrations This is code inserted into the constructors the class. You'll want to call registerPlugin from there.
Definition at line 156 of file kpluginfactory.h.
Member Data Documentation
KPluginFactoryPrivate* const KPluginFactory::d_ptr [protected] |
Definition at line 410 of file kpluginfactory.h.
The documentation for this class was generated from the following files: