• Skip to content
  • Skip to link menu
KDE 4.2 API Reference
  • KDE API Reference
  • kdelibs
  • Sitemap
  • Contact Us
 

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>

Inheritance diagram for KPluginFactory:

Inheritance graph
[legend]

List of all members.


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);
 }

Author:
Matthias Kretz <kretz@kde.org>

Bernhard Loos <nhuh.put@web.de>

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.


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]

Deprecated:

Definition at line 43 of file kpluginfactory.cpp.

KPluginFactory::KPluginFactory ( QObject *  parent  )  [explicit]

Deprecated:

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]

Deprecated:

Definition at line 342 of file kpluginfactory.h.

template<typename T >
KDE_DEPRECATED T* KPluginFactory::create ( QObject *  parent,
const QStringList &  args 
) [inline]

Deprecated:

Definition at line 334 of file kpluginfactory.h.

template<typename T >
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.

template<typename T >
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.

template<typename T >
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.

template<class impl , class ParentType >
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]

Deprecated:

Reimplemented in KGenericFactory< Product, ParentType >, KGenericFactory< KTypeList< Product, ProductListTail >, QObject >, and KGenericFactory< KTypeList< Product, ProductListTail >, KTypeList< ParentType, ParentTypeListTail > >.

Definition at line 134 of file kpluginfactory.cpp.

template<class impl >
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]

Deprecated:

Definition at line 142 of file kpluginfactory.cpp.

void KPluginFactory::objectCreated ( QObject *  object  )  [signal]

template<class T >
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 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)
    

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();
     ...
 };

See also:
K_PLUGIN_FACTORY_DECLARATION

K_PLUGIN_FACTORY_DEFINITION

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
See also:
K_PLUGIN_FACTORY

K_PLUGIN_FACTORY_DEFINITION

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.
See also:
K_PLUGIN_FACTORY

K_PLUGIN_FACTORY_DECLARATION

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:
  • kpluginfactory.h
  • kpluginfactory.cpp

KDECore

Skip menu "KDECore"
  • Main Page
  • Modules
  • Namespace List
  • Class Hierarchy
  • Alphabetical List
  • Class List
  • File List
  • Namespace Members
  • Class Members
  • Related Pages

kdelibs

Skip menu "kdelibs"
  • DNSSD
  • Interfaces
  •   KHexEdit
  •   KMediaPlayer
  •   KSpeech
  •   KTextEditor
  • Kate
  • kconf_update
  • KDE3Support
  •   KUnitTest
  • KDECore
  • KDED
  • KDEsu
  • KDEUI
  • KDocTools
  • KFile
  • KHTML
  • KImgIO
  • KInit
  • kio
  • KIOSlave
  • KJS
  •   KJS-API
  •   WTF
  • kjsembed
  • KNewStuff
  • KParts
  • Kross
  • KUtils
  • Nepomuk
  • Plasma
  • Solid
  • Sonnet
  • ThreadWeaver
Generated for kdelibs by doxygen 1.5.7
This website is maintained by Adriaan de Groot and Allen Winter.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal