[Kst] extragear/graphics/kst/devel-docs/plugins
Adam Treat
treat at kde.org
Wed May 23 20:41:50 CEST 2007
SVN commit 667733 by treat:
* More documentation on basic plugins
M +186 -58 KstBasicPlugins
M +28 -29 StartHere
--- trunk/extragear/graphics/kst/devel-docs/plugins/KstBasicPlugins #667732:667733
@@ -19,9 +19,12 @@
Name=Foo
Comment=A plugin that provides Foo algorithm.
-Your C++ class should inherit KstBasicPlugin and provide implementations of the
-pure virtual methods found in KstBasicPlugin:
+More information on .desktop files can be found here:
+ http://standards.freedesktop.org/desktop-entry-spec/latest/
+Next, your C++ class should inherit KstBasicPlugin and provide implementations
+of the pure virtual methods found in KstBasicPlugin:
+
//The implementation of the algorithm the plugin provides.
//Operates on the inputVectors, inputScalars, and inputStrings
//to produce the outputVectors, outputScalars, and outputStrings.
@@ -37,91 +40,216 @@
virtual QStringList outputScalarList() const = 0;
virtual QStringList outputStringList() const = 0;
-Here is an example of a plugins header file:
+The algorithm method is the heart of the plugin. By reimplementing this method
+the plugin writer can operate on the various inputs to produce the desired output
+vectors, scalars and strings.
-#ifndef FOOPLUGIN_H
-#define FOOPLUGIN_H
+The string lists are simply methods that will return the labels of your expected
+inputs and outputs. These methods are used by the configuration dialog for instance
+to allow the user to specify inputs and name outputs.
-#include <kstbasicplugin.h>
+Here is an example of a plugin's header file:
-class FooPlugin : public KstBasicPlugin {
- Q_OBJECT
- public:
- FooPlugin(QObject *parent, const char *name, const QStringList &args);
- virtual ~FooPlugin();
+ #ifndef FOOPLUGIN_H
+ #define FOOPLUGIN_H
- virtual bool algorithm();
+ #include <kstbasicplugin.h>
- virtual QStringList inputVectorList() const;
- virtual QStringList inputScalarList() const;
- virtual QStringList inputStringList() const;
- virtual QStringList outputVectorList() const;
- virtual QStringList outputScalarList() const;
- virtual QStringList outputStringList() const;
-};
+ class FooPlugin : public KstBasicPlugin {
+ Q_OBJECT
+ public:
+ FooPlugin(QObject *parent, const char *name, const QStringList &args);
+ virtual ~FooPlugin();
-And here is an example of a plugins cpp file:
+ virtual bool algorithm();
-#include "fooplugin.h"
+ virtual QStringList inputVectorList() const;
+ virtual QStringList inputScalarList() const;
+ virtual QStringList inputStringList() const;
+ virtual QStringList outputVectorList() const;
+ virtual QStringList outputScalarList() const;
+ virtual QStringList outputStringList() const;
+ };
-#include <kgenericfactory.h>
+Let's go over it step by step:
-static const QString& VECTOR_IN = KGlobal::staticQString("Vector In");
-static const QString& SCALAR_IN = KGlobal::staticQString("Scalar In");
-static const QString& STRING_IN = KGlobal::staticQString("String In");
-static const QString& VECTOR_OUT = KGlobal::staticQString("Vector Out");
-static const QString& SCALAR_OUT = KGlobal::staticQString("Scalar Out");
-static const QString& STRING_OUT = KGlobal::staticQString("String Out");
+ #ifndef FOOPLUGIN_H
+ #define FOOPLUGIN_H
-K_EXPORT_COMPONENT_FACTORY( kstobject_fooplugin,
- KGenericFactory<FooPlugin>( "kstobject_fooplugin" ) )
+ #include <kstbasicplugin.h>
-FooPlugin::FooPlugin( QObject */*parent*/, const char */*name*/, const QStringList &/*args*/ )
- : KstBasicPlugin() {
-}
+Here we include our base class, KstBasicPlugin and provide a header guard.
+ class FooPlugin : public KstBasicPlugin {
+ Q_OBJECT
-FooPlugin::~FooPlugin() {
-}
+Our plugin declares the class and how it inherits KstBasicPlugin. Our class is also
+marked with the Q_OBJECT macro as KstBasicPlugin inherits QObject. More information
+on QObjects and this macro can be found here:
+ http://doc.trolltech.com/3.3/metaobjects.html#Q_OBJECT
-bool FooPlugin::algorithm() {
- //Do something...
- return true;
-}
+Moving on...
+ public:
+ FooPlugin(QObject *parent, const char *name, const QStringList &args);
+ virtual ~FooPlugin();
-QStringList FooPlugin::inputVectorList() const {
- return QStringList( VECTOR_IN );
-}
+We declare the FooPlugin constructor and destructor. You should use exactly
+these signatures for your plugin. Only change the name... The args are an internal
+function of how KDE loads its plugins.
+ virtual bool algorithm();
-QStringList FooPlugin::inputScalarList() const {
- return QStringList( SCALAR_IN );
-}
+ virtual QStringList inputVectorList() const;
+ virtual QStringList inputScalarList() const;
+ virtual QStringList inputStringList() const;
+ virtual QStringList outputVectorList() const;
+ virtual QStringList outputScalarList() const;
+ virtual QStringList outputStringList() const;
+ };
+These methods are the crux of the matter. These methods will dictate how your
+plugin operates and what it provides. You'll be reimplenting them from KstBasicPlugin.
-QStringList FooPlugin::inputStringList() const {
- return QStringList( STRING_IN );
-}
+And now here is an example of a plugins cpp file:
+ #include "fooplugin.h"
-QStringList FooPlugin::outputVectorList() const {
- return QStringList( VECTOR_OUT );
-}
+ #include <kgenericfactory.h>
+ static const QString& VECTOR_IN = KGlobal::staticQString("Vector In");
+ static const QString& SCALAR_IN = KGlobal::staticQString("Scalar In");
+ static const QString& STRING_IN = KGlobal::staticQString("String In");
+ static const QString& VECTOR_OUT = KGlobal::staticQString("Vector Out");
+ static const QString& SCALAR_OUT = KGlobal::staticQString("Scalar Out");
+ static const QString& STRING_OUT = KGlobal::staticQString("String Out");
-QStringList FooPlugin::outputScalarList() const {
- return QStringList( SCALAR_OUT );
-}
+ K_EXPORT_COMPONENT_FACTORY( kstobject_fooplugin,
+ KGenericFactory<FooPlugin>( "kstobject_fooplugin" ) )
+ FooPlugin::FooPlugin( QObject */*parent*/, const char */*name*/, const QStringList &/*args*/ )
+ : KstBasicPlugin() {
+ }
-QStringList FooPlugin::outputStringList() const {
- return QStringList( STRING_OUT );
-}
-#include "fooplugin.moc"
+ FooPlugin::~FooPlugin() {
+ }
+
+ bool FooPlugin::algorithm() {
+ //Do something...
+ return true;
+ }
+
+
+ QStringList FooPlugin::inputVectorList() const {
+ return QStringList( VECTOR_IN );
+ }
+
+
+ QStringList FooPlugin::inputScalarList() const {
+ return QStringList( SCALAR_IN );
+ }
+
+
+ QStringList FooPlugin::inputStringList() const {
+ return QStringList( STRING_IN );
+ }
+
+
+ QStringList FooPlugin::outputVectorList() const {
+ return QStringList( VECTOR_OUT );
+ }
+
+
+ QStringList FooPlugin::outputScalarList() const {
+ return QStringList( SCALAR_OUT );
+ }
+
+
+ QStringList FooPlugin::outputStringList() const {
+ return QStringList( STRING_OUT );
+ }
+
+ #include "fooplugin.moc"
+
+Let's go over it step by step:
+
+ #include "fooplugin.h"
+
+ #include <kgenericfactory.h>
+
+Include our plugin header and also kgenericfactory.h which is involved in KDE's
+plugin loading system. More information about kgenericfactory.h can be found
+here:
+
+ http://api.kde.org/3.5-api/kdelibs-apidocs/kdecore/html/classKGenericFactory.html
+
+Moving on...
+
+ static const QString& VECTOR_IN = KGlobal::staticQString("Vector In");
+ [...]
+
+Here we store the name of our inputs/outputs in static variables.
+
+ K_EXPORT_COMPONENT_FACTORY( kstobject_fooplugin,
+ KGenericFactory<FooPlugin>( "kstobject_fooplugin" ) )
+
+ FooPlugin::FooPlugin( QObject */*parent*/, const char */*name*/, const QStringList &/*args*/ )
+ : KstBasicPlugin() {
+ }
+
+
+ FooPlugin::~FooPlugin() {
+ }
+
+The macro K_EXPORT_COMPONENT_FACTORY is used by KDE's plugin loading system. You should use it
+along with the contructors and destructors specified here almost verbatim. Only the names
+for your plugin should be substituted with the various Foo, FOO, foo's.
+
+ bool FooPlugin::algorithm() {
+ //Do something...
+ return true;
+ }
+
+This is the meat of your plugin. You'll need to fill out the algorithm according
+to your plugin and operate on the inputs to produce the outputs. Here is the
+how to retrieve the actual input object for the name above:
+
+ KstVectorPtr vectorIn = inputVector(VECTOR_IN);
+
+You can consult the KstDataObject API for other operations on such objects.
+
+ QStringList FooPlugin::inputVectorList() const {
+ return QStringList( VECTOR_IN );
+ }
+ [...]
+
+These simply organize the static strings you created above and return them as
+a set of string lists. Simply construct a QStringList from all the input vectors
+for instance and return this list. This provides KstBasicPlugin with the metadata
+required to populate the configuration dialog for instance. More information
+on QStringList can be found here:
+
+ http://doc.trolltech.com/3.3/qstringlist.html
+
+Finally...
+
+ #include "fooplugin.moc"
+
+This is an included necessary for QObject's meta object system. Information
+about this is located here:
+
+ http://doc.trolltech.com/3.3/moc.html
+
+In order to build your plugin you'll need a copy of Kst. The easiest way to build
+is to include your plugin in Kst's sources in the kst/src/plugin/fooplugin/
+directory. Kst uses autoconf/automake to build its sources and your plugin will
+need a Makefile.am file to specify how to build it. Consult the Makefile.am
+found in kst/src/plugin/linefit for an example. You'll also need a copy of the
+headers and sources required to build kst which means KDE/Qt development sources.
+
The KstBasicPlugin takes care of providing almost everything, including the
configuration widget for your plugin. The one thing it doesn't do is provide
the actual algorithm or the names of the inputs/outputs.
--- trunk/extragear/graphics/kst/devel-docs/plugins/StartHere #667732:667733
@@ -7,46 +7,45 @@
KstPlugins are presently implemented as:
- KstDataSource plugins
- + These provide the ability to read in different file formats or data
- "sources".
+ + These provide the ability to read in different file formats or data
+ "sources".
- KstDataObject plugins
- + These are advanced data plugins that provide their own configuration dialog.
+ + These are advanced data plugins that provide their own configuration dialog.
- KstBasicPlugin plugins
- + These are basic data plugins that inherit KstDataObject plugins, but
- are provided with a default configuration dialog.
-- KstCPlugin plugins
- + These are deprecated data plugins replaced by KstBasicPlugins.
+ + These are basic data plugins that inherit KstDataObject plugins, but
+ are provided with a default configuration dialog.
- Kst Extensions
- + These allow entire subsystems to be added to Kst without touching
- the Kst core.
+ + These allow entire subsystems to be added to Kst without touching
+ the Kst core.
-All KstPlugins except KstCPlugins are KDE style plugins and therefore require
-a .desktop file and must be installed in the KDE standard plugins directories.
-They derive from the base servicetype "Kst/Plugin". This base type includes
-two kst specific properties:
+All KstPlugins are KDE style plugins and therefore require a .desktop file and
+must be installed in the KDE standard plugins directories. They derive from the
+base servicetype "Kst/Plugin". This base type includes two kst specific
+properties:
-X-Kst-Plugin-Author: A string containing the name of the author.
-X-Kst-Plugin-Version: A string containing the version of the plugin.
+ X-Kst-Plugin-Author: A string containing the name of the author.
+ X-Kst-Plugin-Version: A string containing the version of the plugin.
-,desktop files also have additional properties. Here are the required ones:
+.desktop files also have additional properties. Here are the required ones:
-Name: A string containing the name of the plugin. For instance, "My Plugin".
-ServiceTypes: For KstDataSource this is "Kst Data Source" and for KstDataObjects this is "Kst Data Object" etc, etc...
-X-KDE-ModuleType: This should be set to "Plugin".
-X-KDE-Library: The library name. This is not the filename, but a name
- that is used to construct it. For instance, it could
- be "kstobject_myplugin" where the library might be named
- "kstobject_myplugin.so". This must also be a legal C
- variable name as it is used to construct the function
- names inside the library. Note: for KstDataSource plugins the
- name here is shortened even further: the actual library name is
- kstdata_myplugin.so, but you should put "myplugin" as the value
- for this property.
+ Name: A string containing the name of the plugin. For instance, "My Plugin".
+ ServiceTypes: For KstDataSource this is "Kst Data Source" and for KstDataObjects
+ this is "Kst Data Object" etc, etc...
+ X-KDE-ModuleType: This should be set to "Plugin".
+ X-KDE-Library: The library name. This is not the filename, but a name
+ that is used to construct it. For instance, it could
+ be "kstobject_myplugin" where the library might be named
+ "kstobject_myplugin.so". This must also be a legal C
+ variable name as it is used to construct the function
+ names inside the library. Note: for KstDataSource plugins the
+ name here is shortened even further: the actual library name is
+ kstdata_myplugin.so, but you should put "myplugin" as the value
+ for this property.
Some other .desktop properties are also common to all plugins:
-Comment: The description of the plugin.
+ Comment: The description of the plugin.
To find out more about creating these plugins look in the respective file for
the type of plugin you are interested in creating.
More information about the Kst
mailing list