<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
<TITLE>The KMovisto Plugin Development Handbook: Sample</TITLE>
<LINK HREF="kmpi_index-4.html" REL=next>
<LINK HREF="kmpi_index-2.html" REL=previous>
<LINK HREF="kmpi_index.html#toc3" REL=contents>
</HEAD>
<BODY>
<A HREF="kmpi_index-4.html">Next</A>
<A HREF="kmpi_index-2.html">Previous</A>
<A HREF="kmpi_index.html#toc3">Contents</A>
<HR>
<H2><A NAME="s3">3. Sample</A></H2>
<P>
This sample describes the development of a KMovisto export plugin with export Dialog and file management by KMovisto. You will
find a sample program which shows the programming principles but you won't find a complete library here that could be used in any
usefull way than as template. The sample plugin will print out the current molecule data and the filename which should be used to
the standard output.
<P>
<H2><A NAME="ss3.1">3.1 Step1: Preparation</A>
</H2>
<P>
In this description I assume, that you have created a project directory somewhere in your home directory named <I>myplugin</I>
and that you have copied the files <I>iplugin.h</I> and <I>iplugin.cpp</I> (shipped with your KMovisto tar ball or KMovisto
plugin development kit) in this directory. You should not change <I>iplugin.h</I> or <I>iplugin.cpp</I> in any way, so you
may use a static library archive file <I>libiplugin.a</I> instead created by the following commands:
<PRE>
g++ -v -c iplugin.cpp
ar r libiplugin.a iplugin.o
ranlib libiplugin.a
</PRE>
Furthermore you should create the empty files <I>myplugin.h</I> and <I>myplugin.cpp</I>.
<P>
<H2><A NAME="ss3.2">3.2 Step2: Programming and compilation</A>
</H2>
<P>
First of all is the implementation and declaration of the plugin requirements via macros <I>DECLARE_PLUGIN_CLASS</I>/<I>IMPLEMENT_PLUGIN_CLASS(CMyPlugin)</I>
and the declaration of the class CMyPlugin:
<P>
<TABLE border="1" cellspacing="0" cellpadding="0" width="100%">
<TR align="CENTER" bgcolor="#dfefff">
<TD align="CENTER">
<FONT size="+1">myplugin.h</FONT>
</TD>
</TR>
<TR align="LEFT" valign="TOP">
<TD>
<BR>
<P>
<PRE>
/* plugin class declarations */
DECLARE_PLUGIN_CLASS(CMyPlugin)
class CMyPlugin : public CIPluginFileExportDialog
{
};
</PRE>
</P>
</TD>
</TR>
</TABLE>
<P>
<TABLE border="1" cellspacing="0" cellpadding="0" width="100%">
<TR align="CENTER" bgcolor="#dfefff">
<TD align="CENTER">
<FONT size="+1">myplugin.cpp</FONT>
</TD>
</TR>
<TR align="LEFT" valign="TOP">
<TD>
<BR>
<P>
<PRE>
#include "myplugin.h"
/* plugin class implementations */
IMPLEMENT_PLUGIN_CLASS(CMyPlugin)
</PRE>
</P>
</TD>
</TR>
</TABLE>
<P>
CMyPlugin is inherited by CIPluginFileExportDialog, the base class for export plugins with file dialog management. The macro
<I>DECLARE_PLUGIN_CLASS(CMyPlugin)</I> declares a global function which enables KMovisto to create an instance of the
plugin class <I>CMyPlugin</I>. It also includes the <I>using namespace kmpi;</I> for you. <I>DECLARE_PLUGIN_CLASS(CMyPlugin)</I>
provides a declaration of a function which creates the instance of <I>CMyPlugin</I> used by KMovisto.
<P>
Next step is a declaration and implementation of virtual member functions declared by the base classes CIPlugin and
CIPluginFile. Because they are very simple member functions which are only used for providing plugin informations they may
defined in the header file:
<P>
<TABLE border="1" cellspacing="0" cellpadding="0" width="100%">
<TR align="CENTER" bgcolor="#dfefff">
<TD align="CENTER">
<FONT size="+1">myplugin.h</FONT>
</TD>
</TR>
<TR align="LEFT" valign="TOP">
<TD>
<BR>
<P>
<PRE>
#include "iplugin.h"
<P>
/* plugin class declarations */
DECLARE_PLUGIN_CLASS(CMyPlugin)
<P>
class CMyPlugin : public CIPluginFileExportDialog
{
public:
/* plugin properties */
virtual string getName(void) {return(string("My KMovisto Plugin"));};
virtual string getDescription(void) {string("This Plugin demonstrates the developing of KMovisto plugins");};
virtual string getPluginVersion(void) {return(string("0.1.0"));};
virtual string getInterfaceVersion(void) {return(string("1.0.0"));};
virtual string getAuthor(void) {return(string("Mario Hoverath"));};
virtual string getEmail(void) {return(string("mario.hoverath@uni-koeln.de"));};
virtual string getHomepage(void) {return(string("http://members.tripod.de/PageOfMH/index.html"));};
virtual string getLicense(void) {return(string("GPL"));};
virtual string getTooltipText(void) {return(string("Plugin demonstration"));};
virtual string getMenuText(void) {return(string("MyPlugin"));};
virtual string getWhatsThisText(void) {return(string("This Plugin demonstrates the developing of KMovisto plugins"));};
virtual string getStatusText(void) {return(string("MyPlugin is executed"));};
virtual string getHighlightText(void) {return(string("This Plugin demonstrates the developing of KMovisto plugins"));};
};
</PRE>
</P>
</TD>
</TR>
</TABLE>
<P>
<TABLE border="1" cellspacing="0" cellpadding="0" width="100%">
<TR align="CENTER" bgcolor="#dfefff">
<TD align="CENTER">
<FONT size="+1">myplugin.cpp</FONT>
</TD>
</TR>
<TR align="LEFT" valign="TOP">
<TD>
<BR>
<P>
<PRE>
#include "myplugin.h"
/* plugin class implementations */
IMPLEMENT_PLUGIN_CLASS(CMyPlugin)
</PRE>
</P>
</TD>
</TR>
</TABLE>
<P>
At this point we would like to add the following toolbar button icon:
<P>
<img src="./images/kmpi_plugin_icon.jpg">
</P>
As described in <A HREF="kmpi_index-2.html#sss2.2.2">chapter 2.2.2</A></LI> this has to be done by overwriting the member
function <I>virtual const char** getButtonXPM(void)</I>. The xpm bitmap should be stored in a static xpm member variable
like that <I>static const char* xpm[];</I>.
<P>
<TABLE border="1" cellspacing="0" cellpadding="0" width="100%">
<TR align="CENTER" bgcolor="#dfefff">
<TD align="CENTER">
<FONT size="+1">myplugin.h</FONT>
</TD>
</TR>
<TR align="LEFT" valign="TOP">
<TD>
<BR>
<P>
<PRE>
#include "iplugin.h"
/* plugin class declarations */
DECLARE_PLUGIN_CLASS(CMyPlugin)
class CMyPlugin : public CIPluginFileExportDialog
{
public:
/* plugin properties */
virtual string getName(void) {return(string("My KMovisto Plugin"));};
virtual string getDescription(void) {return(string("This Plugin demonstrates the developing of KMovisto plugins"));};
virtual string getPluginVersion(void) {return(string("0.1.0"));};
virtual string getInterfaceVersion(void) {return(string("1.0.0"));};
virtual string getAuthor(void) {return(string("Mario Hoverath"));};
virtual string getEmail(void) {return(string("mario.hoverath@uni-koeln.de"));};
virtual string getHomepage(void) {return(string("http://members.tripod.de/PageOfMH/index.html"));};
virtual string getLicense(void) {return(string("GPL"));};
virtual string getTooltipText(void) {return(string("Plugin demonstration"));};
virtual string getMenuText(void) {return(string("MyPlugin"));};
virtual string getWhatsThisText(void) {return(string("This Plugin demonstrates the developing of KMovisto plugins"));};
virtual string getStatusText(void) {return(string("MyPlugin is executed"));};
virtual string getHighlightText(void) {return(string("This Plugin demonstrates the developing of KMovisto plugins"));};
virtual const char** getButtonXPM(void) {return((const char**)CMyPlugin::xpm);};
protected:
/* protected members */
static const char* xpm[];
};
</PRE>
</P>
</TD>
</TR>
</TABLE>
<P>
<TABLE border="1" cellspacing="0" cellpadding="0" width="100%">
<TR align="CENTER" bgcolor="#dfefff">
<TD align="CENTER">
<FONT size="+1">myplugin.cpp</FONT>
</TD>
</TR>
<TR align="LEFT" valign="TOP">
<TD>
<BR>
<P>
<PRE>
#include "myplugin.h"
<P>
/* plugin class implementations */
IMPLEMENT_PLUGIN_CLASS(CMyPlugin)
<P>
const char* CMyPlugin::xpm[] =
{
"16 16 33 1",
" c None",
". c #000000",
"+ c #FFFF00",
"@ c #AFAFCB",
"# c #A4A4B5",
"$ c #DCDCDC",
"% c #A8A8D5",
"& c #BBBBE3",
"* c #555588",
"= c #8D8DD1",
"- c #7777A4",
"; c #C9C9CF",
"> c #6F6FAE",
", c #AAAAFF",
"' c #4444FF",
") c #C6C6FF",
"! c #595980",
"~ c #9191D0",
"{ c #9999FF",
"] c #646475",
"^ c #6B6B8D",
"/ c #7777CC",
"( c #4F4F93",
"_ c #8484A6",
": c #393971",
"< c #7777DD",
"[ c #606077",
"} c #7D7DE3",
"| c #2D2DCC",
"1 c #5555AA",
"2 c #9191A8",
"3 c #ABABAB",
"4 c #444488",
" .. ",
" .++. ",
" .++++. ",
" .++. ",
" .++. ",
" .... ",
" ",
" @# ",
" $%&*=-$ ",
" $;>,'))!; ",
" ===~*,'{{*]^^^ ",
" ///((,'{{((/// ",
" ###_:,'<<:_### ",
" $[}|112 ",
" 34:## ",
" "
};
</PRE>
</P>
</TD>
</TR>
</TABLE>
<P>
In the last step, the plugin class has to interact with the events <I>KMPI_RESULT onCreate(void);</I>, <I>virtual KMPI_RESULT onDestroy(void);</I> and
<I>virtual KMPI_RESULT onOpenFile(const string& file, string& errorMsg);</I>. The last member function is the main function
which should contain the data export routines in 'real' plugins. This sample plugin dumps molecule data and the export
file name to the standard output.
<P>
<TABLE border="1" cellspacing="0" cellpadding="0" width="100%">
<TR align="CENTER" bgcolor="#dfefff">
<TD align="CENTER">
<FONT size="+1">myplugin.h</FONT>
</TD>
</TR>
<TR align="LEFT" valign="TOP">
<TD>
<BR>
<P>
<PRE>
#include "iplugin.h"<BR>
<P>
/* plugin class declarations */
DECLARE_PLUGIN_CLASS(CMyPlugin)
<P>
class CMyPlugin : public CIPluginFileExportDialog
{
public:
/* plugin properties */
virtual string getName(void) {return(string("My KMovisto Plugin"));};
virtual string getDescription(void) {return(string("This Plugin demonstrates the developing of KMovisto plugins"));};
virtual string getPluginVersion(void) {return(string("0.1.0"));};
virtual string getInterfaceVersion(void) {return(string("1.0.0"));};
virtual string getAuthor(void) {return(string("Mario Hoverath"));};
virtual string getEmail(void) {return(string("mario.hoverath@uni-koeln.de"));};
virtual string getHomepage(void) {return(string("http://members.tripod.de/PageOfMH/index.html"));};
virtual string getLicense(void) {return(string("GPL"));};
virtual string getTooltipText(void) {return(string("Plugin demonstration"));};
virtual string getMenuText(void) {return(string("MyPlugin"));};
virtual string getWhatsThisText(void) {return(string("This Plugin demonstrates the developing of KMovisto plugins"));};
virtual string getStatusText(void) {return(string("MyPlugin is executed"));};
virtual string getHighlightText(void) {return(string("This Plugin demonstrates the developing of KMovisto plugins"));};
virtual const char** getButtonXPM(void) {return((const char**)CMyPlugin::xpm);};
protected:
/* protected members */
static const char* xpm[];
public:
/* events */
virtual KMPI_RESULT onCreate(void);
virtual KMPI_RESULT onDestroy(void);
virtual KMPI_RESULT onOpenFile(const string& file, string& errorMsg);
};
</PRE>
</P>
</TD>
</TR>
</TABLE>
<P>
<TABLE border="1" cellspacing="0" cellpadding="0" width="100%">
<TR align="CENTER" bgcolor="#dfefff">
<TD align="CENTER">
<FONT size="+1">myplugin.cpp</FONT>
</TD>
</TR>
<TR align="LEFT" valign="TOP">
<TD>
<BR>
<P>
<PRE>
#include "myplugin.h"
<P>
/* plugin class implementations */
IMPLEMENT_PLUGIN_CLASS(CMyPlugin)
<P>
const char* CMyPlugin::xpm[] =
{
"16 16 33 1",
" c None",
". c #000000",
"+ c #FFFF00",
"@ c #AFAFCB",
"# c #A4A4B5",
"$ c #DCDCDC",
"% c #A8A8D5",
"& c #BBBBE3",
"* c #555588",
"= c #8D8DD1",
"- c #7777A4",
"; c #C9C9CF",
"> c #6F6FAE",
", c #AAAAFF",
"' c #4444FF",
") c #C6C6FF",
"! c #595980",
"~ c #9191D0",
"{ c #9999FF",
"] c #646475",
"^ c #6B6B8D",
"/ c #7777CC",
"( c #4F4F93",
"_ c #8484A6",
": c #393971",
"< c #7777DD",
"[ c #606077",
"} c #7D7DE3",
"| c #2D2DCC",
"1 c #5555AA",
"2 c #9191A8",
"3 c #ABABAB",
"4 c #444488",
" .. ",
" .++. ",
" .++++. ",
" .++. ",
" .++. ",
" .... ",
" ",
" @# ",
" $%&*=-$ ",
" $;>,'))!; ",
" ===~*,'{{*]^^^ ",
" ///((,'{{((/// ",
" ###_:,'<<:_### ",
" $[}|112 ",
" 34:## ",
" "
};
KMPI_RESULT CMyPlugin::onCreate(void)
{
fprintf(stdout, "CMyPlugin::onCreate called\n");
return(KMPI_SUCCESS);
}
KMPI_RESULT CMyPlugin::onDestroy(void)
{
fprintf(stdout, "CMyPlugin::onDestroy called\n");
return(KMPI_SUCCESS);
}
KMPI_RESULT CMyPlugin::onOpenFile(const string& file, string& errorMsg)
{
unsigned int i = 1;
fprintf(stdout, "CMyPlugin::onOpenFile called\n");
fprintf(stdout, "file=%s\n", file.c_str());
fprintf(stdout, "\nMolecule properties:\n--------------------\n\n*** Atoms: ***\n");
for(i = 1; i <= molecule->getNumberOfAtoms(); i++)
{
fprintf(stdout, "Atom %d: \nNumber=%d\n", i, molecule->getAtomNumber(i));
fprintf(stdout, "Symbol=%s\n", molecule->getAtomSymbol(i).c_str());
fprintf(stdout, "Radius=%f\n", molecule->getAtomRadius(i));
fprintf(stdout, "Position: x=%f y=%f z=%f\n",
molecule->getAtomPosition(i).getPositionX(),
molecule->getAtomPosition(i).getPositionY(),
molecule->getAtomPosition(i).getPositionZ());
fprintf(stdout, "Color: red=%d green=%d blue=%d\n",
molecule->getAtomColor(i).getColorRed(),
molecule->getAtomColor(i).getColorGreen(),
molecule->getAtomColor(i).getColorBlue());
fprintf(stdout, "--------------------\n");
}
fprintf(stdout, "\n*** Bonds: ***\n");
for(i = 1; i <= molecule->getNumberOfBonds(); i++)
{
fprintf(stdout, "Connection between atom%d and atom%d\n",
molecule->getBond(i)->getBondPartner1(),
molecule->getBond(i)->getBondPartner2());
fprintf(stdout, "--------------------\n");
}
fprintf(stdout, "Color: red=%d green=%d blue=%d\n",
molecule->getBondColor().getColorRed(),
molecule->getBondColor().getColorGreen(),
molecule->getBondColor().getColorBlue());
fprintf(stdout, "Radius=%f\n", molecule->getBondRadius());
errorMsg = (string)"";
return(KMPI_SUCCESS);
}
</PRE>
</P>
</TD>
</TR>
</TABLE>
<P>
Now it is time to compile the export plugin. If you use the static library <I>libiplugin.a</I> as described in <A HREF="kmpi_index-3.html#ss3.1">capter 3.1</A>
the library is created with the following command:
<PRE>
g++ -shared -fPIC -L. -o libMyPlugin.so myplugin.cpp -liplugin
</PRE>
Or if the interface sourcecode <I>iplugin.cpp</I> is used instead of a static library:
<PRE>
g++ -shared -fPIC -o libMyPlugin.so myplugin.cpp iplugin.cpp
</PRE>
<P>
<H2><A NAME="ss3.3">3.3 Step3: Installation</A>
</H2>
<P>
The installation of the plugin is as simple as possible: The plugin file <I>libMyPlugin.so</I> should be copied to <I>/usr/lib</I>
to make it available to all users or copied to a local user directory, <I>~/lib</I>, respectively. Now you have the ability to
load the plugin library via KMovisto plugin manager. After loading the plugin the plugin properties are displayed (<B>Fig. 2 - 4</B>):
<P>
<DIV align="center"><img src="./images/kmpi_pluginmanager1.jpg"></DIV>
<P>
<BLOCKQUOTE><CODE>
<PRE>
<B>Fig. 2:</B> Plugin manager - description
</PRE>
</CODE></BLOCKQUOTE>
<P>
<DIV align="center"><img src="./images/kmpi_pluginmanager2.jpg"></DIV>
<P>
<BLOCKQUOTE><CODE>
<PRE>
<B>Fig. 3:</B> Plugin manager - properties
</PRE>
</CODE></BLOCKQUOTE>
<P>
<DIV align="center"><img src="./images/kmpi_pluginmanager3.jpg"></DIV>
<P>
<BLOCKQUOTE><CODE>
<PRE>
<B>Fig. 4:</B> Plugin manager - legacy
</PRE>
</CODE></BLOCKQUOTE>
<P>
When the new plugin is added to KMovisto it is usable immediately via tool bar button or menu (<B>Fig. 5</B>):
<P>
<DIV align="center"><img src="./images/kmpi_menu_toolbar.jpg"></DIV>
<P>
<BLOCKQUOTE><CODE>
<PRE>
<B>Fig. 5:</B> Menu and toolbar entries
</PRE>
</CODE></BLOCKQUOTE>
<P>
The sample plugin includes file funtionality, so the user has also the ability to configure working directories and file
format filters (<B>Fig. 6</B>).
<P>
<DIV align="center"><img src="./images/kmpi_directories.jpg"></DIV>
<P>
<BLOCKQUOTE><CODE>
<PRE>
<B>Fig. 6:</B> Working directory and filter configuration
</PRE>
</CODE></BLOCKQUOTE>
<P>
<HR>
<A HREF="kmpi_index-4.html">Next</A>
<A HREF="kmpi_index-2.html">Previous</A>
<A HREF="kmpi_index.html#toc3">Contents</A>
</BODY>
</HTML>
distrib
>
Mandriva
>
10.0
>
i586
>
media
>
contrib
>
by-pkgid
>
e42466f081a63a01cff2cdde695034f3
>
files
>
47
