Next Previous Contents

2. Development

2.1 Plugin types

The interface supports four plugin types:

The first and the second interface type does not support any additional functionality like file import/export dialog or user defined working directories. These types could be used for plugins which includes their own file dialogs or maybe which use other data sources/targets than files (databases e. g.).

The third and second types are used for plugins which extends KMovisto file import/export funtionality similar to the integrated KMovisto import/export routines. This also includes the configurable user defined working directories.

The interface type depends on the class where the plugin class is derived from, so each plugin library is used for one import or export type.

2.2 Programming Plugins

As described above the plugin interface supports four different import/export types which depends on the class the plugin is derived from. CPluginFileImport, CPluginFileExport, CPluginFileImportDialog and CPluginFileExportDialog are used for this purpose. Furthermore the six classes CIPluginElements, CIPluginAtom, CIPluginBond, CIPluginMolecule, CIPluginColor and CIPluginPosition are used for data exchange and for storing actual settings (Fig. 1).

Fig. 1: Plugin interface class hierarchy

All classes are declared in the namespace kmpi in the header file iplugin.h. Implementations are found in iplugin.cpp which has to be compiled and linked to your library. To avoid upgrade problems, you should not edit these two files directly. It is recommended to create your own header and source files. The only thing you have to do before you start plugin programming is inserting the macro DECLARE_PLUGIN_CLASS(CMyPluginClass) and the #include "iplugin.h" precompiler command in the header file and inserting IMPLEMENT_PLUGIN_CLASS(CMyPluginClass) in the source file, where CMyPluginClass is the class you have derived from one of the four base classes CIPluginFile.... You must not derive your plugin class directly from CIPlugin or CIPluginFile.

2.2.1 Class CIPlugin

Public member functions:

CIPlugin

Detailed Description

CIPlugin is the base class of all types of KMovisto plugins. This class organizes the main plugin informations which are displayed in the KMovisto Plugin manager. CIPlugin is an abstract class so you never use it directly for plugin development. The member functions are mostly declared as virtual function which have to be overwritten in derivated classes. Every inherited plugin class contains protected members elements of type CIPluginElements and molecule of type CIPluginMolecule which are initialised with current setting before the import or export starts.

virtual string getName(void)

Returns the plugin name which is shown in the plugin manager list.

virtual string getDescription(void)

Returns the plugin description which is shown in the plugin manager description. Overwrite this member function to return a detailed description of the plugin.

virtual string getPluginVersion(void)

Returns the plugin version. This version is not proofed by KMovisto, so it can be defined free.

virtual string getInterfaceVersion(void) const

Returns the plugin interface version. This version is proofed by KMovisto and should be the same or smaller as the plugin interface version used by KMovisto.

virtual KMPI_INTERFACE_TYPE getInterfaceType(void) const

Returns the type of the plugin. Valid values of enum type KMPI_INTERFACE_TYPE are KMPI_FILE_IMPORT, KMPI_FILE_IMPORT_DIALOG, KMPI_FILE_EXPORT and KMPI_FILE_EXPORT_DIALOG. They will be defined atomaticaly in classes derived from CIPluginFile so you should not overwrite this function.

virtual string getAuthor(void)

Returns the author of the plugin displayed in the KMovisto plugin manager.

virtual string getEmail(void)

Returns the email address of the plugin author displayed in the KMovisto plugin manager.

virtual string getHomepage(void)

Returns the internet address where to find plugin informations or latest versions. This information is also displayed in the KMovisto plugin manager.

virtual string getLicense(void)

Returns the license of the plugin displayed in the KMovisto plugin manager.

CIPluginMolecule* getMolecule(void)

Returns a pointer of the protected member molecule of the plugin instance. This function is usually used by KMovisto only.

CIPluginElements* getElements(void)

Returns a pointer of the protected member elements of the plugin instance. This function is usually used by KMovisto only.

KMPI_RESULT setMolecule(const CIPluginMolecule& mol)

Initialises the instance molecule of the plugin instance. Returns KMPI_SUCCESS if successfull otherwise returns KMPI_ERROR. This function is usually used by KMovisto only.

KMPI_RESULT setElements(const CIPluginElements& el)

Initialises the instance elements of the plugin instance. Returns KMPI_SUCCESS if successfull otherwise returns KMPI_ERROR. This function is usually used by KMovisto only.

virtual KMPI_RESULT onCreate(void)

This member function is called whenever an instance of the plugin class is created during KMovisto program starts and when the plugin is added using the plugin manager. Initialisations should be done here rather than in the constructor because there is a return value of enum type KMPI_RESULT available.

virtual KMPI_RESULT onDestroy(void)

This member function is called whenever an instance of the plugin class is destroyed during KMovisto program exits and when the plugin is removed using the plugin manager. Any cleanup should be done here rather than in the constructor because there is a return value of enum type KMPI_RESULT available.

2.2.2 Class CIPluginFile

Public member functions:

CIPluginFile

Detailed Description

CIPluginFile inherits CIPlugin and is also an abstract base class. This class declares file import and export specific member functions.

virtual const char** getButtonXPM(void)

Returns a pointer of const char pointer type of the xpm bitmap shown in the plugin toolbar button and in the plugin manager plugin list. The xpm format is not described here but it is a very simple graphic format supported by many graphic programs. Note that the xpm format has to be little bit different from the usual declaration. The extra const makes the entire definition read-only:
static const char* xpm[] = {
"16 15 8 1",
"a c #cec6bd",
....
To obtain a uniform look you should define a button xpm's width and height of 16 pixels.

virtual string getTooltipText(void)

Returns the tool tip of the plugin tool bar button. The tip is a short, single line of text reminding the user of the plugin's function. It is drawn immediately below the region in a distinctive black-on-yellow combination.

virtual string getMenuText(void)

Returns the text of the plugin menu item.

virtual string getWhatsThisText(void)

Returns the "What's this?" help text of the plugin. "What's this?" help is part of an application's online help system. It provides a single window with an explanatory text that pops up when the user asks "What's this?".

virtual string getStatusText(void)

Returns the status text of the plugin function. This text is displayed in the status line of the program window when the plugin function is executed.

virtual string getHighlightText(void)

Returns the status text of the plugin function when the menu item is highlighted.

virtual KMPI_RESULT onOpenFile(const string& file, string& errorMsg)

This member function is called whenever a file is opened. The absolute filename is found in the reference of file if the plugin supports the file import and export dialog functionality of KMovisto, that means the plugin has to be derived from CPluginFileImportDialog and CPluginFileExportDialog otherwise file is an empty string. If file operation errors occured the return value should be KMPI_ERROR. In this case KMovisto displays the string errorMsg otherwise this string value is ignored.

2.2.3 Classes derived from CIPluginFile

Detailed Description

The classes CPluginFileImport, CPluginFileExport, CPluginFileImportDialog and CPluginFileExportDialog are derived directly or indirectly from CPluginFile and have no additional member functions. These classes are used to overload functions of the abstract base classes or declare protected members for the different purposes.

2.2.4 Class CIPluginElements

Public member functions:

CIPluginElements

Detailed Description

CIPluginElements is used to define element properties which could be changed during import or export operations. Every plugin class contains a protected member elements which is initialised with current setting before the import or export starts. The maximum element number is KMPI_MAX_ELEMENT_NUMBER which is currently set to 109. Note the valid element symbols above "Ha" (105) are "Unh" (106), "Uns" (107), "Uno" (108) and "Une" (109).

CIPluginElements& operator=(const CIPluginElements& elements)

Copies element color and radius.

float getRadius(unsigned int number)

Returns the atom radius of the element given by number. If number is not between 0 and KMPI_MAX_ELEMENT_NUMBER the return value is 0.0f.

float getRadius(const string& symbol)

Returns the atom radius of the element given by symbol. If symbol is not a valid element symbol the return value is 0.0f.

CIPluginColor getColor(unsigned int number)

Returns the atom color of the element given by number. If number is not between 0 and KMPI_MAX_ELEMENT_NUMBER the returned color is black (0, 0, 0).

CIPluginColor getColor(const string& symbol)

Returns the atom color of the element given by symbol. If symbol is not a valid element symbol the returned color is black (0, 0, 0).

static string getSymbol(unsigned int number)

Returns the element symbol of the element given by number. If number is not between 0 and KMPI_MAX_ELEMENT_NUMBER the return value is empty.

static unsigned int getNumber(const string& symbol)

Returns the element number of the element given by symbol. If symbol is not a valid element symbol the return value is 0.

KMPI_RESULT setRadius(unsigned int number, float radius)

Sets the element radius of the element given by number and returns KMPI_SUCCESS if successfull. If number is not between 0 and KMPI_MAX_ELEMENT_NUMBER the return value is KMPI_ERROR.

KMPI_RESULT setRadius(const string& symbol, float radius)

Sets the element radius of the element given by symbol and returns KMPI_SUCCESS if successfull. If symbol is not a valid element symbol the return value is KMPI_ERROR.

KMPI_RESULT setColor(unsigned int number, const CIPluginColor& color)

Sets the element color of the element given by number and returns KMPI_SUCCESS if successfull. If number is not between 0 and KMPI_MAX_ELEMENT_NUMBER the return value is KMPI_ERROR.

KMPI_RESULT setColor(const string& symbol, const CIPluginColor& color)

Sets the element color of the element given by symbol and returns KMPI_SUCCESS if successfull. If symbol is not a valid element symbol the return value is KMPI_ERROR.

2.2.5 Class CIPluginAtom

Public member functions:

CIPluginAtom

Detailed Description

This class represents a single atom and it's coordinates (atom units) in a molecule.

CIPluginAtom& operator=(const CIPluginAtom& atom)

Copies atom coordinates, number, symbol, radius and color.

unsigned int getNumber(void)

Returns the element number of the atom.

string getSymbol(void)

Returns the element symbol of the atom.

CIPluginPosition getPosition(void)

Returns the element coordinates of the atom.

CIPluginColor getColor(void)

Returns the element color of the atom.

float getRadius(void)

Returns the element radius of the atom.

KMPI_RESULT setByNumber(const CIPluginElements* pElements, unsigned int number)

Initialise the atom properties by using an instance of CIPluginElements and the atom number. If number is not between 0 and KMPI_MAX_ELEMENT_NUMBER the return value is KMPI_ERROR otherwise the return value is KMPI_SUCCESS.

KMPI_RESULT setBySymbol(const CIPluginElements* pElements, const string& symbol)

Initialise the atom properties by using an instance of CIPluginElements and the atom symbol. If symbol is not a valid element symbol the return value is KMPI_ERROR otherwise the return value is KMPI_SUCCESS.

KMPI_RESULT setPosition(const CIPluginPosition& position)

Sets the atom position and returns KMPI_SUCCESS.

KMPI_RESULT setPosition(float x = 0.0f, float y = 0.0f, float z = 0.0f)

Sets the atom position and returns KMPI_SUCCESS.

KMPI_RESULT setColor(const CIPluginColor& color)

Sets the atom color and returns KMPI_SUCCESS.

KMPI_RESULT setColor(unsigned int red, unsigned int green, unsigned int blue)

Sets the atom color and returns KMPI_SUCCESS if the values red, green and blue are between 0 and 255.

KMPI_RESULT setRadius(float radius)

Sets the atom radius and returns KMPI_SUCCESS if radius is 0 or greater.

2.2.6 Class CIPluginBond

Public member functions:

CIPluginBond

Detailed Description

This class CIPluginBond represents a single connection between atoms in a molecule. Note that bond properties which are set only once as bond color or radius are set in the molecule.

CIPluginBond& operator=(const CIPluginBond& bond)

Copies connected atoms.

unsigned int getBondPartner1(void)

Returns the index of the first bond partner.

unsigned int getBondPartner2(void)

Returns the index of the the second bond partner.

KMPI_RESULT setBondPartner(unsigned int index1, unsigned int index2)

Sets the atom indexes of connected atoms. Atom indexes start with 1.

2.2.7 Class CIPluginMolecule

Public member functions:

CIPluginMolecule

Detailed Description

The class CIPluginMolecule represents a molecule.

CIPluginMolecule& operator=(const CIPluginMolecule& molecule)

Copies all molecule properties.

unsigned int addAtom(const CIPluginAtom& atom)

Adds a new atom to the molecule and returns the index of the added atom if successfull. Otherwise the member function returns 0. The atom is defined by a CIPluginAtom type.

unsigned int addAtom(const CIPluginElements* pElements, unsigned int number)

Adds a new atom to the molecule and returns the index of the added atom if successfull. Otherwise the member function returns 0. The atom is defined by a pointer of an instance of CIPluginElements and the element number of the atom.

unsigned int addAtom(const CIPluginElements* pElements, const string& symbol)

Adds a new atom to the molecule and returns the index of the added atom if successfull. Otherwise the member function returns 0. The atom is defined by a pointer of an instance of CIPluginElements and the element symbol of the atom.

unsigned int addBond(const CIPluginBond& bond)

Adds a new bond to the molecule and returns the index of the added bond if successfull. Otherwise the member function returns 0.

unsigned int addBond(unsigned int index1, unsigned int index2)

Adds a new bond to the molecule and returns the index of the added bond if successfull. Otherwise the member function returns 0.

KMPI_RESULT deleteAtom(unsigned int index, KMPI_BOOL deleteBonds = TRUE)

Deletes the atom with index number index and returns KMPI_SUCCESS if successfull. By default all connections between the deleted atom and other atoms are deleted too if deleteBonds is not set to FALSE.

KMPI_RESULT deleteBond(unsigned int index1, unsigned int index2)

Deletes the bond between atoms indexed by index1 and index2. If successfull the return value is KMPI_SUCCESS otherwise the return value is KMPI_ERROR.

KMPI_RESULT deleteAll(KMPI_BOOL deleteAtoms = TRUE, KMPI_BOOL deleteBonds = TRUE)

By default this member function deletes all atoms and bonds and returns KMPI_SUCCESS if successfull. If deleteAtoms and/or deleteBonds is set to FALSE atoms and/or bond are not deleted.

unsigned int getNumberOfAtoms(void)

Returns the number of atoms in the molecule.

unsigned int getNumberOfBonds(void)

Returns the number of bonds in the molecule.

CIPluginAtom* getAtom(unsigned int index)

Returns a pointer to an instance of CIPluginAtom of the atom indexed by indey if successfull otherwise returns NULL.

unsigned int getAtomNumber(unsigned int index)

Returns the element number of the atom indexed by a valid index. Otherwise returns 0.

string getAtomSymbol(unsigned int index)

Returns the element symbol of the atom indexed by a valid index. Otherwise returns an empty string.

CIPluginPosition getAtomPosition(unsigned int index)

Returns the coordinates of the atom indexed by index. If index is not a valid index the coordinates are set to (0, 0, 0).

CIPluginColor getAtomColor(unsigned int index)

Returns the color of the atom indexed by index. If index is not a valid index the color is set to black (0, 0, 0).

float getAtomRadius(unsigned int index)

Returns the radius of the atom indexed by index. If index is not a valid index the radius is set to 0.0f.

CIPluginBond* getBond(unsigned int index)

Returns a pointer to an instance of CIPluginBond of the bond indexed by index if successfull otherwise returns NULL.

CIPluginColor getBondColor(void)

Returns the color of the bond indexed by index. If index is not a valid index the color is set to black (0, 0, 0).

float getBondRadius(void)

Returns the radius of the bond indexed by index. If index is not a valid index the radius is set to 0.0f.

string getTitle(void)

Returns the title of the molecule.

KMPI_RESULT setAtomByNumber(unsigned int index, const CIPluginElements* pElements, unsigned int number)

Sets the Atom properties of the atom indexed by index using a pointer to a instance of CIPluginElements and the element number. If successfull the return value is KMPI_SUCCESS otherwise it is KMPI_ERROR.

KMPI_RESULT setAtomBySymbol(unsigned int index, const CIPluginElements* pElements, const string& symbol)

Sets the Atom properties of the atom indexed by index using a pointer to a instance of CIPluginElements and the element symbol. If successfull the return value is KMPI_SUCCESS otherwise it is KMPI_ERROR.

KMPI_RESULT setAtomPosition(unsigned int index, const CIPluginPosition& position)

Sets the coordinates of the atom indexed by index using a reference to a CIPluginPosition. If successfull the return value is KMPI_SUCCESS otherwise it is KMPI_ERROR.

KMPI_RESULT setAtomPosition(unsigned int index, float x = 0.0f, float y = 0.0f, float z = 0.0f)

Sets the coordinates of the atom indexed by index using x, y, and z coordinates. If successfull the return value is KMPI_SUCCESS otherwise it is KMPI_ERROR.

KMPI_RESULT setAtomColor(unsigned int index, const CIPluginColor& color)

Sets the color of the atom indexed by index using a reference to a CIPluginColor. If successfull the return value is KMPI_SUCCESS otherwise it is KMPI_ERROR.

KMPI_RESULT setAtomColor(unsigned int index, unsigned int red, unsigned int green, unsigned int blue)

Sets the color of the atom indexed by index using red, green and blue values. If successfull the return value is KMPI_SUCCESS otherwise it is KMPI_ERROR. Note that valid values of red, green and blue are between 0 and 255.

KMPI_RESULT setAtomRadius(unsigned int index, float radius)

Sets the radius of the atom indexed by index. If successfull the return value is KMPI_SUCCESS otherwise it is KMPI_ERROR.

KMPI_RESULT setBondColor(const CIPluginColor& color)

Sets the color of the bond using a reference to a CIPluginColor. If successfull the return value is KMPI_SUCCESS otherwise it is KMPI_ERROR.

KMPI_RESULT setBondColor(unsigned int red, unsigned int green, unsigned int blue)

Sets the color of the bond using red, green and blue values. If successfull the return value is KMPI_SUCCESS otherwise it is KMPI_ERROR. Note that valid values of red, green and blue are between 0 and 255.

KMPI_RESULT setBondRadius(float radius)

Sets the radius of the bond. If successfull the return value is KMPI_SUCCESS otherwise it is KMPI_ERROR.

KMPI_RESULT setTitle(const string& title)

Sets the title of the molecule and returns KMPI_SUCCESS

KMPI_BOOL isConnected(unsigned int index1, unsigned int index2)

Checks if the atoms indexed by index1 and index2 are connected. Returns TRUE if a bond exists otherwise returns FALSE.

KMPI_RESULT makeBonds(float bondFactor = 1.12f)

This member function connects atoms automaticly depending on their atom radius and the value of bondFactor. Atom1 and atom2 will be connected if the following condition is true:
(radius(atom1) + radius(atom2)) * bondFactor >= distance(atom1, atom2)

2.2.8 Class CIPluginColor

Public member functions:

CIPluginColor

Detailed Description

This class provides colors based on RGB values.

CIPluginColor(unsigned int red = 0, unsigned int green = 0, unsigned int blue = 0)

Constructs a color with the RGB value red, green and blue. Note that RGB values must be in the range 0 - 255.

CIPluginColor& operator=(const CIPluginColor& color)

Copies RGB values.

unsigned int getColorRed(void)

Returns the red component of the RGB triplet.

unsigned int getColorGreen(void)

Returns the green component of the RGB triplet.

unsigned int getColorBlue(void)

Returns the blue component of the RGB triplet.

KMPI_RESULT setColor(unsigned int red, unsigned int green, unsigned int blue)

Sets the RGB value to red, green and blue. The arguments, red, green and blue must all be in the range 0 - 255. If any of them are outside the legal range, the color component is set to the maximum value of 255 and the return value is KMPI_ERROR otherwise it is KMPI_SUCCESS.

KMPI_RESULT setColorRed(unsigned int red)

Sets the red component to red. The argument must be in the range 0 - 255. If it is outside the legal range, the color component is set to the maximum value of 255 and the return value is KMPI_ERROR otherwise it is KMPI_SUCCESS.

KMPI_RESULT setColorGreen(unsigned int green)

Sets the green component to green. The argument must be in the range 0 - 255. If it is outside the legal range, the color component is set to the maximum value of 255 and the return value is KMPI_ERROR otherwise it is KMPI_SUCCESS.

KMPI_RESULT setColorBlue(unsigned int blue)

Sets the blue component to blue. The argument must be in the range 0 - 255. If it is outside the legal range, the color component is set to the maximum value of 255 and the return value is KMPI_ERROR otherwise it is KMPI_SUCCESS.

2.2.9 Class CIPluginPosition

Public member functions:

CIPluginPosition

Detailed Description

This class represents a coordinate (atom units).

CIPluginPosition(float x = 0.0f, float y = 0.0f, float z = 0.0f)

Constructs a coordinate with x, y, and z values.

CIPluginPosition& operator=(const CIPluginPosition& position)

Copies a coordinate.

float getPositionX(void)

Returns the x component of a coordinate.

float getPositionY(void)

Returns the y component of a coordinate.

float getPositionZ(void)

Returns the z component of a coordinate.

static float getDistance(const CIPluginPosition& position1, const CIPluginPosition& position2)

Returns the distance between two coordinates.

KMPI_RESULT setPosition(float x, float y, float z)

Sets the coordinate and returns KMPI_SUCCESS.

KMPI_RESULT setPositionX(float x)

Sets the x component of the coordinate and returns KMPI_SUCCESS.

KMPI_RESULT setPositionY(float y)

Sets the y component of the coordinate and returns KMPI_SUCCESS.

KMPI_RESULT setPositionZ(float z)

Sets the z component of the coordinate and returns KMPI_SUCCESS.


Next Previous Contents